<!DOCTYPE html><html lang="en"><head>
  <meta charset="utf-8">
  <meta name="generator" content="ReSpec 32.1.8">
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  <style>
  span.example-title{text-transform:none}
  :is(aside,div).example,div.illegal-example{padding:.5em;margin:1em 0;position:relative;clear:both}
  div.illegal-example{color:red}
  div.illegal-example p{color:#000}
  :is(aside,div).example{border-left-width:.5em;border-left-style:solid;border-color:#e0cb52;background:#fcfaee}
  aside.example div.example{border-left-width:.1em;border-color:#999;background:#fff}
  .example pre{background-color:rgba(0,0,0,.03)}
  </style>
  <style>
  .issue-label{text-transform:initial}
  .warning>p:first-child{margin-top:0}
  .warning{padding:.5em;border-left-width:.5em;border-left-style:solid}
  span.warning{padding:.1em .5em .15em}
  .issue.closed span.issue-number{text-decoration:line-through}
  .warning{border-color:#f11;border-width:.2em;border-style:solid;background:#fbe9e9}
  .warning-title:before{content:"⚠";font-size:1.3em;float:left;padding-right:.3em;margin-top:-.3em}
  li.task-list-item{list-style:none}
  input.task-list-item-checkbox{margin:0 .35em .25em -1.6em;vertical-align:middle}
  .issue a.respec-gh-label{padding:5px;margin:0 2px 0 2px;font-size:10px;text-transform:none;text-decoration:none;font-weight:700;border-radius:4px;position:relative;bottom:2px;border:none;display:inline-block}
  </style>
  <style>
  dfn{cursor:pointer}
  .dfn-panel{position:absolute;z-index:35;min-width:300px;max-width:500px;padding:.5em .75em;margin-top:.6em;font-family:"Helvetica Neue",sans-serif;font-size:small;background:#fff;color:#000;box-shadow:0 1em 3em -.4em rgba(0,0,0,.3),0 0 1px 1px rgba(0,0,0,.05);border-radius:2px}
  .dfn-panel:not(.docked)>.caret{position:absolute;top:-9px}
  .dfn-panel:not(.docked)>.caret::after,.dfn-panel:not(.docked)>.caret::before{content:"";position:absolute;border:10px solid transparent;border-top:0;border-bottom:10px solid #fff;top:0}
  .dfn-panel:not(.docked)>.caret::before{border-bottom:9px solid #a2a9b1}
  .dfn-panel *{margin:0}
  .dfn-panel b{display:block;color:#000;margin-top:.25em}
  .dfn-panel ul a[href]{color:#333}
  .dfn-panel>div{display:flex}
  .dfn-panel a.self-link{font-weight:700;margin-right:auto}
  .dfn-panel .marker{padding:.1em;margin-left:.5em;border-radius:.2em;text-align:center;white-space:nowrap;font-size:90%;color:#040b1c}
  .dfn-panel .marker.dfn-exported{background:#d1edfd;box-shadow:0 0 0 .125em #1ca5f940}
  .dfn-panel .marker.idl-block{background:#8ccbf2;box-shadow:0 0 0 .125em #0670b161}
  .dfn-panel a:not(:hover){text-decoration:none!important;border-bottom:none!important}
  .dfn-panel a[href]:hover{border-bottom-width:1px}
  .dfn-panel ul{padding:0}
  .dfn-panel li{margin-left:1em}
  .dfn-panel.docked{position:fixed;left:.5em;top:unset;bottom:2em;margin:0 auto;max-width:calc(100vw - .75em * 2 - .5em - .2em * 2);max-height:30vh;overflow:auto}
  </style>


  <title>Design Tokens Format Module</title>

  <meta name="color-scheme" content="light dark">

  <style>

        :root {
          /* Remove watermark negatively impacting readability */
          --unofficial-watermark: none !important;
        }
        .rfc2119 {
          font-style: normal;
          font-size: 0.875em;
        }

  </style>

  <style id="respec-mainstyle">
  @keyframes pop{
  0%{transform:scale(1,1)}
  25%{transform:scale(1.25,1.25);opacity:.75}
  100%{transform:scale(1,1)}
  }
  :is(h1,h2,h3,h4,h5,h6,a) abbr{border:none}
  dfn{font-weight:700}
  a.internalDFN{color:inherit;border-bottom:1px solid #99c;text-decoration:none}
  a.externalDFN{color:inherit;border-bottom:1px dotted #ccc;text-decoration:none}
  a.bibref{text-decoration:none}
  .respec-offending-element:target{animation:pop .25s ease-in-out 0s 1}
  .respec-offending-element,a[href].respec-offending-element{text-decoration:red wavy underline}
  @supports not (text-decoration:red wavy underline){
  .respec-offending-element:not(pre){display:inline-block}
  .respec-offending-element{background:url() bottom repeat-x}
  }
  #references :target{background:#eaf3ff;animation:pop .4s ease-in-out 0s 1}
  cite .bibref{font-style:normal}
  code{color:#c63501}
  th code{color:inherit}
  a[href].orcid{padding-left:4px;padding-right:4px}
  a[href].orcid>svg{margin-bottom:-2px}
  .toc a,.tof a{text-decoration:none}
  a .figno,a .secno{color:#000}
  ol.tof,ul.tof{list-style:none outside none}
  .caption{margin-top:.5em;font-style:italic}
  table.simple{border-spacing:0;border-collapse:collapse;border-bottom:3px solid #005a9c}
  .simple th{background:#005a9c;color:#fff;padding:3px 5px;text-align:left}
  .simple th a{color:#fff;padding:3px 5px;text-align:left}
  .simple th[scope=row]{background:inherit;color:inherit;border-top:1px solid #ddd}
  .simple td{padding:3px 10px;border-top:1px solid #ddd}
  .simple tr:nth-child(even){background:#f0f6ff}
  .section dd>p:first-child{margin-top:0}
  .section dd>p:last-child{margin-bottom:0}
  .section dd{margin-bottom:1em}
  .section dl.attrs dd,.section dl.eldef dd{margin-bottom:0}
  #issue-summary>ul{column-count:2}
  #issue-summary li{list-style:none;display:inline-block}
  details.respec-tests-details{margin-left:1em;display:inline-block;vertical-align:top}
  details.respec-tests-details>*{padding-right:2em}
  details.respec-tests-details[open]{z-index:999999;position:absolute;border:thin solid #cad3e2;border-radius:.3em;background-color:#fff;padding-bottom:.5em}
  details.respec-tests-details[open]>summary{border-bottom:thin solid #cad3e2;padding-left:1em;margin-bottom:1em;line-height:2em}
  details.respec-tests-details>ul{width:100%;margin-top:-.3em}
  details.respec-tests-details>li{padding-left:1em}
  .self-link:hover{opacity:1;text-decoration:none;background-color:transparent}
  aside.example .marker>a.self-link{color:inherit}
  .header-wrapper{display:flex;align-items:baseline}
  :is(h2,h3,h4,h5,h6):not(#toc>h2,#abstract>h2,#sotd>h2,.head>h2){position:relative;left:-.5em}
  :is(h2,h3,h4,h5,h6):not(#toch2)+a.self-link{color:inherit;order:-1;position:relative;left:-1.1em;font-size:1rem;opacity:.5}
  :is(h2,h3,h4,h5,h6)+a.self-link::before{content:"§";text-decoration:none;color:var(--heading-text)}
  :is(h2,h3)+a.self-link{top:-.2em}
  :is(h4,h5,h6)+a.self-link::before{color:#000}
  @media (max-width:767px){
  dd{margin-left:0}
  }
  @media print{
  .removeOnSave{display:none}
  }
  </style>
  <meta name="description" content="This document describes the technical specification for a file format to
          exchange design tokens between different tools.">
  <style>
  var:hover{text-decoration:underline;cursor:pointer}
  var.respec-hl{color:var(--color,#000);background-color:var(--bg-color);box-shadow:0 0 0 2px var(--bg-color)}
  @media (prefers-color-scheme:dark){
  var.respec-hl{filter:saturate(.9) brightness(.9)}
  }
  var.respec-hl-c1{--bg-color:#f4d200}
  var.respec-hl-c2{--bg-color:#ff87a2}
  var.respec-hl-c3{--bg-color:#96e885}
  var.respec-hl-c4{--bg-color:#3eeed2}
  var.respec-hl-c5{--bg-color:#eacfb6}
  var.respec-hl-c6{--bg-color:#82ddff}
  var.respec-hl-c7{--bg-color:#ffbcf2}
  @media print{
  var.respec-hl{background:0 0;color:#000;box-shadow:unset}
  }
  </style>
  <style>
  .hljs{display:block;overflow-x:auto;padding:.5em;color:#383a42;background:#fafafa}
  .hljs-comment,.hljs-quote{color:#717277;font-style:italic}
  .hljs-doctag,.hljs-formula,.hljs-keyword{color:#a626a4}
  .hljs-deletion,.hljs-name,.hljs-section,.hljs-selector-tag,.hljs-subst{color:#ca4706;font-weight:700}
  .hljs-literal{color:#0b76c5}
  .hljs-addition,.hljs-attribute,.hljs-meta-string,.hljs-regexp,.hljs-string{color:#42803c}
  .hljs-built_in,.hljs-class .hljs-title{color:#9a6a01}
  .hljs-attr,.hljs-number,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-pseudo,.hljs-template-variable,.hljs-type,.hljs-variable{color:#986801}
  .hljs-bullet,.hljs-link,.hljs-meta,.hljs-selector-id,.hljs-symbol,.hljs-title{color:#336ae3}
  .hljs-emphasis{font-style:italic}
  .hljs-strong{font-weight:700}
  .hljs-link{text-decoration:underline}
  </style>
  <style>
  var{position:relative;cursor:pointer}
  var[data-type]::after,var[data-type]::before{position:absolute;left:50%;top:-6px;opacity:0;transition:opacity .4s;pointer-events:none}
  var[data-type]::before{content:"";transform:translateX(-50%);border-width:4px 6px 0 6px;border-style:solid;border-color:transparent;border-top-color:#000}
  var[data-type]::after{content:attr(data-type);transform:translateX(-50%) translateY(-100%);background:#000;text-align:center;font-family:"Dank Mono","Fira Code",monospace;font-style:normal;padding:6px;border-radius:3px;color:#daca88;text-indent:0;font-weight:400}
  var[data-type]:hover::after,var[data-type]:hover::before{opacity:1}
  </style>
  <script id="initialUserConfig" type="application/json">{
    "specStatus": "CG-DRAFT",
    "thisVersion": "https://www.designtokens.org/TR/second-editors-draft/format/",
    "prevVersion": "https://www.designtokens.org/TR/first-editors-draft/format/",
    "latestVersion": "https://www.designtokens.org/TR/third-editors-draft/format/",
    "edDraftURI": null,
    "subtitle": "Second Editors’ Draft",
    "group": "design-tokens",
    "publishDate": "2022-06-14",
    "isPreview": false,
    "editors": [
      {
        "name": "Daniel Banks",
        "url": "https://twitter.com/dbanksDesign"
      },
      {
        "name": "Donna Vitan",
        "url": "http://twitter.com/donnavitan"
      },
      {
        "name": "James Nash",
        "url": "https://cirrus.twiddles.com/"
      },
      {
        "name": "Kevin Powell",
        "url": "https://twitter.com/kevinmpowell"
      },
      {
        "name": "Louis Chenais",
        "url": "https://twitter.com/chuckn0risk"
      }
    ],
    "github": {
      "repoURL": "https://github.com/design-tokens/community-group",
      "branch": "second-editors-draft"
    },
    "tocIntroductory": false,
    "logos": [
      {
        "src": "/assets/dtcg-logo-on-color.svg",
        "url": "https://www.designtokens.org",
        "alt": "Design Tokens Community Group",
        "width": 128,
        "height": 128,
        "id": "dtcg-logo"
      }
    ],
    "publishISODate": "2022-06-14T00:00:00.000Z",
    "generatedSubtitle": "Draft Community Group Report 14 June 2022"
  }</script>
  <link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2021/cg-draft">
  <link rel="stylesheet" media="(prefers-color-scheme: dark)" href="https://www.w3.org/StyleSheets/TR/2021/dark.css"></head>
    <body class="h-entry"><div class="head">
      <p class="logos"><a class="logo" href="https://www.designtokens.org"><img crossorigin="" alt="Design Tokens Community Group" height="128" id="dtcg-logo" src="/assets/dtcg-logo-on-color.svg" width="128" style="background:none">
    </a></p>
      <h1 id="title" class="title">Design Tokens Format Module</h1> <h2 id="subtitle" class="subtitle">Second Editors’ Draft</h2>
      <p id="w3c-state">
        <a href="https://www.w3.org/standards/types#reports">Draft Community Group Report</a>
        <time class="dt-published" datetime="2022-06-14">14 June 2022</time>
      </p>
      <dl>
        <dt>This version:</dt><dd>
                <a class="u-url" href="https://www.designtokens.org/TR/second-editors-draft/format/">https://www.designtokens.org/TR/second-editors-draft/format/</a>
              </dd>
        <dt>Latest published version:</dt><dd>
                <a href="https://www.designtokens.org/TR/third-editors-draft/format/">https://www.designtokens.org/TR/third-editors-draft/format/</a>
              </dd>



        <dt>Previous version:</dt><dd><a href="https://www.designtokens.org/TR/first-editors-draft/format/">https://www.designtokens.org/TR/first-editors-draft/format/</a></dd>

        <dt>Editors:</dt><dd class="editor p-author h-card vcard">
      <a class="u-url url p-name fn" href="https://twitter.com/dbanksDesign">Daniel Banks</a>
    </dd><dd class="editor p-author h-card vcard">
      <a class="u-url url p-name fn" href="http://twitter.com/donnavitan">Donna Vitan</a>
    </dd><dd class="editor p-author h-card vcard">
      <a class="u-url url p-name fn" href="https://cirrus.twiddles.com/">James Nash</a>
    </dd><dd class="editor p-author h-card vcard">
      <a class="u-url url p-name fn" href="https://twitter.com/kevinmpowell">Kevin Powell</a>
    </dd><dd class="editor p-author h-card vcard">
      <a class="u-url url p-name fn" href="https://twitter.com/chuckn0risk">Louis Chenais</a>
    </dd>


        <dt>Feedback:</dt><dd>
          <a href="https://github.com/design-tokens/community-group/">GitHub design-tokens/community-group</a>
          (<a href="https://github.com/design-tokens/community-group/pulls/">pull requests</a>,
          <a href="https://github.com/design-tokens/community-group/issues/new/choose">new issue</a>,
          <a href="https://github.com/design-tokens/community-group/issues/">open issues</a>)
        </dd>
      </dl>


      <hr title="Separator for header">
    </div>


      <section id="abstract" class="introductory"><h2>Abstract</h2>
        <p>
          This document describes the technical specification for a file format to
          exchange design tokens between different tools.
        </p>
      </section>

      <section id="sotd" class="introductory"><h2>Status of This Document</h2><p>
        This specification was published by the
        <a href="https://www.w3.org/groups/cg/design-tokens">Design Tokens Community Group</a>. It is not a W3C Standard nor is it
        on the W3C Standards Track.

              Please note that under the
              <a href="https://www.w3.org/community/about/agreements/cla/">W3C Community Contributor License Agreement (CLA)</a>
                          there is a limited opt-out and other conditions apply.

        Learn more about
        <a href="https://www.w3.org/community/">W3C Community and Business Groups</a>.
      </p>
        <p>
          This section describes the status of this document at the time of its
          publication. Other documents may supersede this document. A list of
          current W3C Community Group reports and the latest revision of this
          report can be found in the W3C Community Group reports index at
          <a href="https://www.w3.org/community/reports/">https://www.w3.org/community/reports/</a>.
        </p>
        <p>
          This document was published by the DTCG as a
          <a href="https://www.w3.org/policies/process/#RecsWD">Working Draft</a>
          following the definitions provided by the W3C process. It is provided for
          discussion only and may change at any moment. Its publication here does not
          imply endorsement of its contents by W3C or the Design Tokens Community Group
          Membership. Don’t cite this document other than as work in progress.
        </p>
        <p>
          While not a W3C recommendation, this classification is intended to
          clarify that, after extensive consensus-building, this specification is
          intended for implementation.
        </p>
        <p>
          This specification is considered unstable, and should not be implemented.
        </p>
      <p>
      <a href="https://github.com/design-tokens/community-group/issues/">GitHub Issues</a> are preferred for
            discussion of this specification.

    </p></section><nav id="toc"><h2 class="introductory" id="table-of-contents">Table of Contents</h2><ol class="toc"><li class="tocline"><a class="tocxref" href="#abstract">Abstract</a></li><li class="tocline"><a class="tocxref" href="#sotd">Status of This Document</a></li><li class="tocline"><a class="tocxref" href="#conformance"><bdi class="secno">1. </bdi>Conformance</a></li><li class="tocline"><a class="tocxref" href="#introduction"><bdi class="secno">2. </bdi>Introduction</a></li><li class="tocline"><a class="tocxref" href="#terminology"><bdi class="secno">3. </bdi>Terminology</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#design-token"><bdi class="secno">3.1 </bdi>(Design) Token</a></li><li class="tocline"><a class="tocxref" href="#design-token-properties"><bdi class="secno">3.2 </bdi>(Design) Token Properties</a></li><li class="tocline"><a class="tocxref" href="#design-tool"><bdi class="secno">3.3 </bdi><span data-plurals="design tools">Design tool</span></a></li><li class="tocline"><a class="tocxref" href="#translation-tool"><bdi class="secno">3.4 </bdi><span data-plurals="translation tools">Translation tool</span></a></li><li class="tocline"><a class="tocxref" href="#type"><bdi class="secno">3.5 </bdi>Type</a></li><li class="tocline"><a class="tocxref" href="#groups"><bdi class="secno">3.6 </bdi>Groups</a></li><li class="tocline"><a class="tocxref" href="#alias-reference"><bdi class="secno">3.7 </bdi>Alias (Reference)</a></li><li class="tocline"><a class="tocxref" href="#composite-design-token"><bdi class="secno">3.8 </bdi>Composite (Design) Token</a></li></ol></li><li class="tocline"><a class="tocxref" href="#file-format"><bdi class="secno">4. </bdi>File format</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#media-type-mime-type"><bdi class="secno">4.1 </bdi>Media type (MIME type)</a></li><li class="tocline"><a class="tocxref" href="#file-extensions"><bdi class="secno">4.2 </bdi>File extensions</a></li></ol></li><li class="tocline"><a class="tocxref" href="#design-token-0"><bdi class="secno">5. </bdi>Design token</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#name-and-value"><bdi class="secno">5.1 </bdi>Name and value</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#character-restrictions"><bdi class="secno">5.1.1 </bdi>Character restrictions</a></li></ol></li><li class="tocline"><a class="tocxref" href="#additional-properties"><bdi class="secno">5.2 </bdi>Additional properties</a></li><li class="tocline"><a class="tocxref" href="#description"><bdi class="secno">5.3 </bdi>Description</a></li><li class="tocline"><a class="tocxref" href="#type-0"><bdi class="secno">5.4 </bdi>Type</a></li><li class="tocline"><a class="tocxref" href="#extensions"><bdi class="secno">5.5 </bdi>Extensions</a></li><li class="tocline"><a class="tocxref" href="#more-token-properties-tbc"><bdi class="secno">5.6 </bdi>More token properties TBC</a></li></ol></li><li class="tocline"><a class="tocxref" href="#groups-0"><bdi class="secno">6. </bdi>Groups</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#additional-group-properties"><bdi class="secno">6.1 </bdi>Additional group properties</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#description-0"><bdi class="secno">6.1.1 </bdi>Description</a></li><li class="tocline"><a class="tocxref" href="#type-1"><bdi class="secno">6.1.2 </bdi>Type</a></li></ol></li><li class="tocline"><a class="tocxref" href="#use-cases"><bdi class="secno">6.2 </bdi>Use-cases</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#file-authoring-organization"><bdi class="secno">6.2.1 </bdi>File authoring &amp; organization</a></li><li class="tocline"><a class="tocxref" href="#gui-tools"><bdi class="secno">6.2.2 </bdi>GUI tools</a></li><li class="tocline"><a class="tocxref" href="#export-tools"><bdi class="secno">6.2.3 </bdi>Export tools</a></li></ol></li></ol></li><li class="tocline"><a class="tocxref" href="#aliases-references"><bdi class="secno">7. </bdi>Aliases / references</a></li><li class="tocline"><a class="tocxref" href="#types"><bdi class="secno">8. </bdi>Types</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#color"><bdi class="secno">8.1 </bdi>Color</a></li><li class="tocline"><a class="tocxref" href="#dimension"><bdi class="secno">8.2 </bdi>Dimension</a></li><li class="tocline"><a class="tocxref" href="#font-family"><bdi class="secno">8.3 </bdi>Font family</a></li><li class="tocline"><a class="tocxref" href="#font-weight"><bdi class="secno">8.4 </bdi>Font weight</a></li><li class="tocline"><a class="tocxref" href="#duration"><bdi class="secno">8.5 </bdi>Duration</a></li><li class="tocline"><a class="tocxref" href="#cubic-bezier"><bdi class="secno">8.6 </bdi>Cubic Bézier</a></li><li class="tocline"><a class="tocxref" href="#additional-types"><bdi class="secno">8.7 </bdi>Additional types</a></li></ol></li><li class="tocline"><a class="tocxref" href="#composite-types"><bdi class="secno">9. </bdi>Composite types</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#groups-versus-composite-tokens"><bdi class="secno">9.1 </bdi>Groups versus composite tokens</a></li><li class="tocline"><a class="tocxref" href="#stroke-style"><bdi class="secno">9.2 </bdi>Stroke style</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#string-value"><bdi class="secno">9.2.1 </bdi>String value</a></li><li class="tocline"><a class="tocxref" href="#object-value"><bdi class="secno">9.2.2 </bdi>Object value</a></li><li class="tocline"><a class="tocxref" href="#fallbacks"><bdi class="secno">9.2.3 </bdi>Fallbacks</a></li></ol></li><li class="tocline"><a class="tocxref" href="#border"><bdi class="secno">9.3 </bdi>Border</a></li><li class="tocline"><a class="tocxref" href="#transition"><bdi class="secno">9.4 </bdi>Transition</a></li><li class="tocline"><a class="tocxref" href="#shadow"><bdi class="secno">9.5 </bdi>Shadow</a></li><li class="tocline"><a class="tocxref" href="#gradient"><bdi class="secno">9.6 </bdi>Gradient</a></li><li class="tocline"><a class="tocxref" href="#typography"><bdi class="secno">9.7 </bdi>Typography</a></li></ol></li><li class="tocline"><a class="tocxref" href="#issue-summary"><bdi class="secno">A. </bdi>Issue summary</a></li><li class="tocline"><a class="tocxref" href="#references"><bdi class="secno">B. </bdi>References</a><ol class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><bdi class="secno">B.1 </bdi>Normative references</a></li></ol></li></ol></nav>

      <section id="conformance"><div class="header-wrapper"><h2 id="x1-conformance"><bdi class="secno">1. </bdi>Conformance</h2><a class="self-link" href="#conformance" aria-label="Permalink for Section 1."></a></div><p>As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.</p><p>
          The key words <em class="rfc2119">MAY</em>, <em class="rfc2119">MUST</em>, <em class="rfc2119">MUST NOT</em>, <em class="rfc2119">SHOULD</em>, and <em class="rfc2119">SHOULD NOT</em> in this document
          are to be interpreted as described in
          <a href="https://datatracker.ietf.org/doc/html/bcp14">BCP 14</a>
          [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc2119" title="Key words for use in RFCs to Indicate Requirement Levels">RFC2119</a></cite>] [<cite><a class="bibref" data-link-type="biblio" href="#bib-rfc8174" title="Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words">RFC8174</a></cite>]
          when, and only when, they appear in all capitals, as shown here.
        </p></section>

      <section id="introduction"><div class="header-wrapper"><h2 id="x2-introduction"><bdi class="secno">2. </bdi>Introduction</h2><a class="self-link" href="#introduction" aria-label="Permalink for Section 2."></a></div>


        <p>
          <em>This section is non normative</em>
        </p>
        <p>
          Design tokens are a methodology for expressing design decisions in a
          platform-agnostic way so that they can be shared across different
          disciplines, tools, and technologies. They help establish a common
          vocabulary across organizations.
        </p>
        <p>
          There is a growing ecosystem of tools for design system maintainers and
          consumers that incorporate design token functionality, or would benefit
          from doing so:
        </p>
        <ul>
          <li>
            <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-1">Design tools</a> have begun allowing designers to label and reference
            shared values for design properties like colors and sizes.
          </li>
          <li>
            <a data-link-type="dfn" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-1">Translation tools</a> exist that can convert source design token data
            into platform-specific source code that can directly be used by
            developers.
          </li>
          <li>
            Documentation tools can display design token names rather than the raw
            values in design specs and style guides.
          </li>
        </ul>
        <p>
          It is often desirable for design system teams to integrate such tools
          together, so that design token data can flow between design and
          development tools.
        </p>
        <p>For example:</p>
        <ul>
          <li>
            Extracting design tokens from design files and feeding them into
            <a data-link-type="dfn" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-2">translation tools</a> to then be converted into platform-specific code
          </li>
          <li>
            Maintaining a "single source of truth" for design tokens and
            automatically keeping design and development tools in sync with it
          </li>
        </ul>
        <p>
          While many tools now offer APIs to access design tokens or the ability
          to export design tokens as a file, these are all tool-specific. The
          burden is therefore on design system teams to create and maintain their
          own, bespoke "glue" code or workflows. Furthermore, if teams want to
          migrate to different tools, they will need to update those integrations.
        </p>
        <p>
          This specification aims to facilitate better interoperability between
          tools and thus lower the work design system teams need to do to
          integrate them by defining a standard file format for expressing design
          token data.
        </p>
      </section>

      <section id="terminology"><div class="header-wrapper"><h2 id="x3-terminology"><bdi class="secno">3. </bdi>Terminology</h2><a class="self-link" href="#terminology" aria-label="Permalink for Section 3."></a></div>
  <p>These definitions are focused on the technical aspects of the specification, aimed at implementers such as <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-2">design tool</a> vendors. Definitions for designers and developers are available at <a href="https://www.designtokens.org/glossary/">designtokens.org</a>.</p>
  <section id="design-token"><div class="header-wrapper"><h3 id="x3-1-design-token"><bdi class="secno">3.1 </bdi>(Design) Token</h3><a class="self-link" href="#design-token" aria-label="Permalink for Section 3.1"></a></div>
  <p>Information associated with a name, at minimum a name/value pair.</p>
  <p>For example:</p>
  <ul>
  <li><code>color-text-primary: #000000;</code></li>
  <li><code>font-size-heading-level-1: 44px;</code></li>
  </ul>
  <p>The name may be associated with additional <a href="#design-token-properties">Token Properties</a>.</p>
  </section><section id="design-token-properties-0"><div class="header-wrapper"><h3 id="design-token-properties"><bdi class="secno">3.2 </bdi>(Design) Token Properties</h3><a class="self-link" href="#design-token-properties" aria-label="Permalink for Section 3.2"></a></div>

  <p>Information associated with a token name.</p>
  <p>For example:</p>
  <ul>
  <li>Value</li>
  <li>Type</li>
  <li>Metadata</li>
  <li>Description</li>
  </ul>
  </section><section id="design-tool"><div class="header-wrapper"><h3 id="x3-3-design-tool"><bdi class="secno">3.3 </bdi><dfn data-plurals="design tools" id="dfn-design-tool" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Design tool</dfn></h3><a class="self-link" href="#design-tool" aria-label="Permalink for Section 3.3"></a></div>
  <p>Visual design creation and editing tools.</p>
  <p>This includes:</p>
  <ul>
  <li>Bitmap image manipulation programs:<ul>
  <li>Photoshop</li>
  <li>Affinity Photo</li>
  <li>Paint.net</li>
  </ul>
  </li>
  <li>Vector graphics tools:<ul>
  <li>Illustrator</li>
  <li>Inkscape</li>
  </ul>
  </li>
  <li>UI design and prototyping tools:<ul>
  <li>Adobe XD</li>
  <li>UXPin</li>
  <li>Sketch</li>
  <li>Figma</li>
  <li>...</li>
  </ul>
  </li>
  </ul>
  </section><section id="translation-tool"><div class="header-wrapper"><h3 id="x3-4-translation-tool"><bdi class="secno">3.4 </bdi><dfn data-plurals="translation tools" id="dfn-translation-tool" tabindex="0" aria-haspopup="dialog" data-dfn-type="dfn">Translation tool</dfn></h3><a class="self-link" href="#translation-tool" aria-label="Permalink for Section 3.4"></a></div>
  <p>Token translation tools are tools that translate token data from one format to another.</p>
  <p>For example:</p>
  <ul>
  <li><a href="https://github.com/salesforce-ux/theo">Theo</a></li>
  <li><a href="https://amzn.github.io/style-dictionary/">Style Dictionary</a></li>
  <li><a href="https://diez.org/">Diez</a></li>
  <li><a href="https://specifyapp.com/">Specify</a></li>
  </ul>
  </section><section id="type"><div class="header-wrapper"><h3 id="x3-5-type"><bdi class="secno">3.5 </bdi>Type</h3><a class="self-link" href="#type" aria-label="Permalink for Section 3.5"></a></div>
  <p>A token's type is a predefined categorization applied to the token's value.</p>
  <p>For example:</p>
  <ul>
  <li>Color</li>
  <li>Size</li>
  <li>Duration</li>
  </ul>
  <p>Token tools can use Types to infer the purpose of a token.</p>
  <p>For example:</p>
  <ul>
  <li>A <a data-link-type="dfn" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-3">translation tool</a> might reference a token's type to convert the source value into the correct platform-specific format.</li>
  <li>A visual <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-3">design tool</a> might reference type to present tokens in the appropriate part of their UI - as in, color tokens are listed in the color picker, font tokens in the text styling UI's fonts list, and so on.</li>
  </ul>
  </section><section id="groups"><div class="header-wrapper"><h3 id="x3-6-groups"><bdi class="secno">3.6 </bdi>Groups</h3><a class="self-link" href="#groups" aria-label="Permalink for Section 3.6"></a></div>
  <p>Sets of tokens belonging to a specific category.</p>
  <p>For example:</p>
  <ul>
  <li>Brand</li>
  <li>Alert</li>
  <li>Layout</li>
  </ul>
  <p>Groups are arbitrary and tools <em class="rfc2119">SHOULD NOT</em> use them to infer the type or purpose of design tokens.</p>
  </section><section id="alias-reference"><div class="header-wrapper"><h3 id="x3-7-alias-reference"><bdi class="secno">3.7 </bdi>Alias (Reference)</h3><a class="self-link" href="#alias-reference" aria-label="Permalink for Section 3.7"></a></div>
  <p>A design token's value can be a reference to another token. The same value can have multiple names or <em>aliases</em>.</p>
  <p>The following Sass example illustrates this concept:</p>
  <pre><code class="scss hljs" aria-busy="false">$color-palette-black: #000000;
  $color-text-primary: $color-palette-black;
  </code></pre>
  <p>The value of <code>$color-text-primary</code> is <code>#000000</code>, because <code>$color-text-primary</code> <em>references <code>$color-palette-black</code></em>. We can also say <code>$color-text-primary</code> is an <em>alias</em> for <code>$color-palette-black.</code></p>
  </section><section id="composite-design-token"><div class="header-wrapper"><h3 id="x3-8-composite-design-token"><bdi class="secno">3.8 </bdi>Composite (Design) Token</h3><a class="self-link" href="#composite-design-token" aria-label="Permalink for Section 3.8"></a></div>
  <p>A design token whose value is made up of multiple, named child values. Composite tokens are useful for closely related style properties that are always applied together. For example, a typography style might be made up of a font name, font size, line height, and color.</p>
  <p>Here's <a href="https://design-tokens.github.io/community-group/format/#example-composite-token-example">an example of a composite shadow token</a>:</p>
  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"shadow-token"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"shadow"</span>,
      <span class="hljs-attr">"$value"</span>: {
        <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#00000088"</span>,
        <span class="hljs-attr">"offsetX"</span>: <span class="hljs-string">"0.5rem"</span>,
        <span class="hljs-attr">"offsetY"</span>: <span class="hljs-string">"0.5rem"</span>,
        <span class="hljs-attr">"blur"</span>: <span class="hljs-string">"1.5rem"</span>,
        <span class="hljs-attr">"spread"</span>: <span class="hljs-string">"0rem"</span>
      }
    }
  }
  </code></pre>
  </section></section>

      <section id="file-format"><div class="header-wrapper"><h2 id="x4-file-format"><bdi class="secno">4. </bdi>File format</h2><a class="self-link" href="#file-format" aria-label="Permalink for Section 4."></a></div>
  <p>Design token files are JSON (<a href="https://www.json.org/">https://www.json.org/</a>) files that adhere to the structure described in this specification.</p>
  <p>JSON was chosen as an interchange format on the basis of:</p>
  <ul>
  <li>Broad support in many programming languages' standard libraries. This is expected to lower barriers to entry for developers writing software that supports design token files.</li>
  <li>Current popularity and widespread use. This is expected to lower the learning curve as many people will already be familiar with JSON.</li>
  <li>Being text-based (rather than binary) allows hand-editing design token files without needing specialized software other than a basic text editor. It also means the files are somewhat human-readable.</li>
  </ul>
  <section id="media-type-mime-type"><div class="header-wrapper"><h3 id="x4-1-media-type-mime-type"><bdi class="secno">4.1 </bdi>Media type (MIME type)</h3><a class="self-link" href="#media-type-mime-type" aria-label="Permalink for Section 4.1"></a></div>
  <p>When serving design token files via HTTP / HTTPS or in any other scenario where a media type (formerly known as MIME type) needs to be specified, the following MIME type <em class="rfc2119">SHOULD</em> be used for design token files:</p>
  <ul>
  <li><code>application/design-tokens+json</code></li>
  </ul>
  <p>However, since every design token file is a valid JSON file, they <em class="rfc2119">MAY</em> be served using the JSON media type: <code>application/json</code>. The above, more specific media type is preferred and <em class="rfc2119">SHOULD</em> be used wherever possible.</p>
  <p>Tools that can open design token files <em class="rfc2119">MUST</em> support both media types.</p>
  </section><section id="file-extensions"><div class="header-wrapper"><h3 id="x4-2-file-extensions"><bdi class="secno">4.2 </bdi>File extensions</h3><a class="self-link" href="#file-extensions" aria-label="Permalink for Section 4.2"></a></div>
  <p>When saving design token files on a local file system, it can be useful to have a distinct file extension as this makes them easier to spot in file browsers. It may also help to associate a file icon and a preferred application for opening those files. The following file extensions are recommended by this spec:</p>
  <ul>
  <li><code>.tokens</code></li>
  <li><code>.tokens.json</code></li>
  </ul>
  <p>The former is more succinct. However, until this format is widely adopted and supported, the latter might be useful to make design token files open in users' preferred JSON editors.</p>
  <p>Tools that can open design token files <em class="rfc2119">MAY</em> filter available files (e.g. in an open file dialog) to only show ones using those extensions. It is recommended to also provide users with a way of opening files that do not use those extensions (e.g. a "show all files" option or similar).</p>
  <p>Tools that can save design token files <em class="rfc2119">SHOULD</em> append one of the recommended file extensions to the filename when saving.</p>
  <div class="note" id="issue-container-generatedID"><div role="heading" class="ednote-title marker" id="h-ednote" aria-level="4"><span>Editor's note</span><span class="issue-label">: JSON schema</span></div><p class="">
    The group is currently exploring the addition of a JSON Schema to support the spec.
  </p></div>

  <div class="note" id="issue-container-generatedID-0"><div role="heading" class="ednote-title marker" id="h-ednote-0" aria-level="4"><span>Editor's note</span><span class="issue-label">: JSON file size limitations</span></div><p class="">
    A concern about file size limitations of JSON files was raised by one of the vendors. The working group continues to gather feedback about any limitations the JSON format imposes.
  </p></div></section></section>

      <section id="design-token-0"><div class="header-wrapper"><h2 id="x5-design-token"><bdi class="secno">5. </bdi>Design token</h2><a class="self-link" href="#design-token-0" aria-label="Permalink for Section 5."></a></div>
  <section id="name-and-value"><div class="header-wrapper"><h3 id="x5-1-name-and-value"><bdi class="secno">5.1 </bdi>Name and value</h3><a class="self-link" href="#name-and-value" aria-label="Permalink for Section 5.1"></a></div>
  <aside class="example" id="example-minimal-file-with-single-design-token"><div class="marker">
      <a class="self-link" href="#example-minimal-file-with-single-design-token">Example<bdi> 1</bdi></a><span class="example-title">: Minimal file with single design token</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"token name"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"token value"</span>
    }
  }
  </code></pre>
  </aside>

  <p>An object with a <strong><code>$value</code></strong> property is a token. Thus, <code>$value</code> is a reserved word in our spec, meaning you can't have a token whose name is "$value". The parent object's key is the token name.</p>
  <p>The example above therefore defines 1 design token with the following properties:</p>
  <ul>
  <li>Name: "token name"</li>
  <li>Value: "token value"</li>
  </ul>
  <p>Name and value are both <strong>required</strong>.</p>
  <p>Token names are case-sensitive, so the following example with 2 tokens in the same group whose names only differ in case is valid:</p>
  <aside class="example" id="example-2"><div class="marker">
      <a class="self-link" href="#example-2">Example<bdi> 2</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"font-size"</span>: { <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"3rem"</span> },
    <span class="hljs-attr">"FONT-SIZE"</span>: { <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"16px"</span> }
  }
  </code></pre>
  </aside>

  <p>However, some tools <em class="rfc2119">MAY</em> need to transform names when exporting to other languages or displaying names to the user, so having token names that differ only in case is likely to cause identical and undesirable duplicates in the output. For example, an export tool that converts these tokens to Sass code would generate problematic output like this:</p>
  <aside class="example" id="example-3"><div class="marker">
      <a class="self-link" href="#example-3">Example<bdi> 3</bdi></a>
    </div>

  <pre><code class="scss hljs" aria-busy="false">$font-size: 3rem;
  $font-size: 16px;

  // The 2nd $font-size overrides the 1st one, so the 1st token
  // has essentially been lost.
  </code></pre>
  </aside>

  <p>Tools <em class="rfc2119">MAY</em> display a warning when token names differ only by case.</p>
  <section id="character-restrictions"><div class="header-wrapper"><h4 id="x5-1-1-character-restrictions"><bdi class="secno">5.1.1 </bdi>Character restrictions</h4><a class="self-link" href="#character-restrictions" aria-label="Permalink for Section 5.1.1"></a></div>
  <p>All properties defined by this format are prefixed with the dollar sign (<code>$</code>). This convention will also be used for any new properties introduced by future versions of this spec. Therefore, token and <a href="#groups-0">group</a> names <em class="rfc2119">MUST NOT</em> begin with the <code>$</code> character.</p>
  <p>Furthermore, due to the syntax used for <a href="#aliases-references">token aliases</a> the following characters <em class="rfc2119">MUST NOT</em> be used anywhere in a token or group name:</p>
  <ul>
  <li><code>{</code> (left curly bracket)</li>
  <li><code>}</code> (right curly bracket)</li>
  <li><code>.</code> (period)</li>
  </ul>
  <div class="note" id="issue-container-generatedID-1"><div role="heading" class="ednote-title marker" id="h-ednote-1" aria-level="5"><span>Editor's note</span><span class="issue-label">: '$' Prefix Rationale</span></div><p class="">
    Because of the <a href="#additional-group-properties">decision to prefix group properties with a dollar sign</a> (<code>$</code>), token properties will also use a dollar sign prefix. This provides a consistent syntax across the spec.
  </p></div>

  </section></section><section id="additional-properties"><div class="header-wrapper"><h3 id="x5-2-additional-properties"><bdi class="secno">5.2 </bdi>Additional properties</h3><a class="self-link" href="#additional-properties" aria-label="Permalink for Section 5.2"></a></div>
  <p>While <code>$value</code> is the only required property for a token, a number of additional properties <em class="rfc2119">MAY</em> be added:</p>
  </section><section id="description"><div class="header-wrapper"><h3 id="x5-3-description"><bdi class="secno">5.3 </bdi>Description</h3><a class="self-link" href="#description" aria-label="Permalink for Section 5.3"></a></div>
  <p>A plain text description explaining the token's purpose can be provided via the optional <code>$description</code> property. Tools <em class="rfc2119">MAY</em> use the description in various ways.</p>
  <p>For example:</p>
  <ul>
  <li>Style guide generators <em class="rfc2119">MAY</em> display the description text alongside a visual preview of the token</li>
  <li>IDEs <em class="rfc2119">MAY</em> display the description as a tooltip for auto-completion (similar to how API docs are displayed)</li>
  <li><a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-4">Design tools</a> <em class="rfc2119">MAY</em> display the description as a tooltip or alongside tokens wherever they can be selected</li>
  <li>Export tools <em class="rfc2119">MAY</em> render the description to a source code comment alongside the variable or constant they export.</li>
  </ul>
  <p>The value of the <code>$description</code> property <em class="rfc2119">MUST</em> be a plain JSON string, for example:</p>
  <aside class="example" id="example-4"><div class="marker">
      <a class="self-link" href="#example-4">Example<bdi> 4</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Button background"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#777777"</span>,
      <span class="hljs-attr">"$description"</span>: <span class="hljs-string">"The background color for buttons in their normal state."</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="type-0"><div class="header-wrapper"><h3 id="x5-4-type"><bdi class="secno">5.4 </bdi>Type</h3><a class="self-link" href="#type-0" aria-label="Permalink for Section 5.4"></a></div>
  <p>Design tokens always have an unambiguous type, so that tools can reliably interpret their value.</p>
  <p>A token's type can be specified by the optional <code>$type</code> property. If the <code>$type</code> property is not set on a token, then the token's type <em class="rfc2119">MUST</em> be determined as follows:</p>
  <ul>
  <li>If the token's value is a reference, then its type is the type of the token being referenced.</li>
  <li>Otherwise, if any of the token's parent groups have a <code>$type</code> property, then the token's type is inherited from the closest parent group with a <code>$type</code> property.</li>
  <li>Otherwise, the token's type is whichever of the basic JSON types (<code>string</code>, <code>number</code>, <code>boolean</code>, <code>object</code>, <code>array</code> or <code>null</code>) its value is.</li>
  </ul>
  <p>Tools <em class="rfc2119">MUST NOT</em> attempt to guess the type of a token by inspecting the contents of its value.</p>
  <p>The <code>$type</code> property can be set on different levels:</p>
  <ul>
  <li>at the group level</li>
  <li>at the token level</li>
  </ul>
  <p>The <code>$type</code> property <em class="rfc2119">MUST</em> be a plain JSON string, whose value is <code>string</code>, <code>number</code>, <code>boolean</code>, <code>object</code>, <code>array</code>, <code>null</code> or one of the values specified in respective <a href="#types">type chapters</a>. The value of <code>$type</code> is case-sensitive.</p>
  <p>For example:</p>
  <aside class="example" id="example-5"><div class="marker">
      <a class="self-link" href="#example-5">Example<bdi> 5</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Button background"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#777777"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="extensions"><div class="header-wrapper"><h3 id="x5-5-extensions"><bdi class="secno">5.5 </bdi>Extensions</h3><a class="self-link" href="#extensions" aria-label="Permalink for Section 5.5"></a></div>
  <p>The optional <strong><code>$extensions</code></strong> property is an object where tools <em class="rfc2119">MAY</em> add proprietary, user-, team- or vendor-specific data to a design token. When doing so, each tool <em class="rfc2119">MUST</em> use a vendor-specific key whose value <em class="rfc2119">MAY</em> be any valid JSON data.</p>
  <ul>
  <li>The keys <em class="rfc2119">SHOULD</em> be chosen such that they avoid the likelihood of a naming clash with another vendor's data. The <a href="https://en.wikipedia.org/wiki/Reverse_domain_name_notation">reverse domain name notation</a> is recommended for this purpose.</li>
  <li>Tools that process design token files <em class="rfc2119">MUST</em> preserve any extension data they do not themselves understand. For example, if a design token contains extension data from tool A and the file containing that data is opened by tool B, then tool B <em class="rfc2119">MUST</em> include the original tool A extension data whenever it saves a new design token file containing that token.</li>
  </ul>
  <aside class="example" id="example-6"><div class="marker">
      <a class="self-link" href="#example-6">Example<bdi> 6</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Button background"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#777777"</span>,
      <span class="hljs-attr">"$extensions"</span>: {
        <span class="hljs-attr">"org.example.tool-a"</span>: <span class="hljs-number">42</span>,
        <span class="hljs-attr">"org.example.tool-b"</span>: {
          <span class="hljs-attr">"turn-up-to-11"</span>: <span class="hljs-literal">true</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  <p>In order to maintain interoperability between tools that support this format, teams and tools <em class="rfc2119">SHOULD</em> restrict their usage of extension data to optional meta-data that is not crucial to understanding that token's value.</p>
  <p>Tool vendors are encouraged to publicly share specifications of their extension data wherever possible. That way other tools can add support for them without needing to reverse engineer the extension data. Popular extensions could also be incorporated as standardized features in future revisions of this specification.</p>
  <div class="note" id="issue-container-generatedID-2"><div role="heading" class="ednote-title marker" id="h-ednote-2" aria-level="4"><span>Editor's note</span><span class="issue-label">: Extensions section</span></div><p class="">
    The extensions section is not limited to vendors. All token users can add additional data in this section for their own purposes.
  </p></div>

  </section><section id="more-token-properties-tbc"><div class="header-wrapper"><h3 id="x5-6-more-token-properties-tbc"><bdi class="secno">5.6 </bdi>More token properties TBC</h3><a class="self-link" href="#more-token-properties-tbc" aria-label="Permalink for Section 5.6"></a></div>
  </section></section>

      <section id="groups-0"><div class="header-wrapper"><h2 id="x6-groups"><bdi class="secno">6. </bdi>Groups</h2><a class="self-link" href="#groups-0" aria-label="Permalink for Section 6."></a></div>
  <p>A file <em class="rfc2119">MAY</em> contain many tokens and they <em class="rfc2119">MAY</em> be nested arbitrarily in groups like so:</p>
  <aside class="example" id="example-7"><div class="marker">
      <a class="self-link" href="#example-7">Example<bdi> 7</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"token uno"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"token value 1"</span>
    },
    <span class="hljs-attr">"token group"</span>: {
      <span class="hljs-attr">"token dos"</span>: {
        <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"token value 2"</span>
      },
      <span class="hljs-attr">"nested token group"</span>: {
        <span class="hljs-attr">"token tres"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"token value 3"</span>
        },
        <span class="hljs-attr">"Token cuatro"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"token value 4"</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  <p>The names of the groups leading to a given token (including that token's name) are that token's <em>path</em>, which is a computed property. <strong>It is not specified in the file</strong>, but parsers that conform to this spec <em class="rfc2119">MUST</em> be able to expose the path of a token. The above example, therefore, defines 4 design tokens with the following properties:</p>
  <ul>
  <li>Token #1<ul>
  <li>Name: "token uno"</li>
  <li>Path: "token uno"</li>
  <li>Value: "token value 1"</li>
  </ul>
  </li>
  <li>Token #2<ul>
  <li>Name: "token dos"</li>
  <li>Path: "token group" / "token dos"</li>
  <li>Value: "token value 2"</li>
  </ul>
  </li>
  <li>Token #3<ul>
  <li>Name: "token tres"</li>
  <li>Path: "token group" / "nested token group" / "token tres"</li>
  <li>Value: "token value 3"</li>
  </ul>
  </li>
  <li>Token #4<ul>
  <li>Name: "token cuatro"</li>
  <li>Path: "token group" / "nested token group" / "token cuatro"</li>
  <li>Value: "token value 4"</li>
  </ul>
  </li>
  </ul>
  <p>Because groupings are arbitrary, tools <em class="rfc2119">MUST NOT</em> use them to infer the type or purpose of design tokens.</p>
  <p>Groups items (i.e. the tokens and/or nested groups) are unordered. In other words, there is no implicit order between items within a group. Therefore, tools that parse or write design token files are not required to preserve the source order of items in a group.</p>
  <p>The names of items in a group are case sensitive. As per the guidance in the <a href="#name-and-value">design token chapter</a>, tools <em class="rfc2119">MAY</em> display a warning to users when groups contain items whose names differ only in case and could therefore lead to naming clashes when exported.</p>
  <div class="note" id="issue-container-generatedID-3"><div role="heading" class="ednote-title marker" id="h-ednote-3" aria-level="3"><span>Editor's note</span><span class="issue-label">: Naming practices</span></div><p class="">
    The format editors acknowledge existing best-practices for token naming, but place no direct constraints on naming via the specification.
  </p></div>

  <section id="additional-group-properties"><div class="header-wrapper"><h3 id="x6-1-additional-group-properties"><bdi class="secno">6.1 </bdi>Additional group properties</h3><a class="self-link" href="#additional-group-properties" aria-label="Permalink for Section 6.1"></a></div>
  <div class="note" id="issue-container-generatedID-4"><div role="heading" class="ednote-title marker" id="h-ednote-4" aria-level="4"><span>Editor's note</span><span class="issue-label">: Group properties vs. nested group and token names</span></div><div class="">

  <p>To prevent collisions with token names, token properties are prefixed with a dollar sign (<code>$</code>). Using this prefix eliminates the need for a reserved words list and helps future-proof the spec.</p>
  <p>Group keys without a dollar sign (<code>$</code>) prefix denote:</p>
  <ul>
  <li><p><strong>A token name:</strong> distinguishable by containing a <code>$value</code> property</p>
  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Group of tokens"</span>: {
      <span class="hljs-attr">"$description"</span>: <span class="hljs-string">"This is an example of a group containing a single token"</span>,
      <span class="hljs-attr">"Token name"</span>: {
        <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#000000"</span>
      }
    }
  }
  </code></pre>
  </li>
  <li><p><strong>A nested group name:</strong> distinguishable by <em>not</em> having a <code>$value</code> property</p>
  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Group of tokens"</span>: {
      <span class="hljs-attr">"$description"</span>: <span class="hljs-string">"This is an example of a group containing a nested group"</span>,
      <span class="hljs-attr">"Subgroup of tokens"</span>: {
        <span class="hljs-attr">"Token 1 name"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#aabbcc"</span>
        },
        <span class="hljs-attr">"Token 2 name"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#ddeeff"</span>
        }
      }
    }
  }
  </code></pre>
  </li>
  </ul>
  </div></div>

  <section id="description-0"><div class="header-wrapper"><h4 id="x6-1-1-description"><bdi class="secno">6.1.1 </bdi>Description</h4><a class="self-link" href="#description-0" aria-label="Permalink for Section 6.1.1"></a></div>
  <p>Groups <em class="rfc2119">MAY</em> include an optional <code>$description</code> property, whose value <em class="rfc2119">MUST</em> be a plain JSON string. Its purpose is to describe the group itself.</p>
  <p>For example:</p>
  <aside class="example" id="example-8"><div class="marker">
      <a class="self-link" href="#example-8">Example<bdi> 8</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"brand"</span>: {
      <span class="hljs-attr">"$description"</span>: <span class="hljs-string">"Design tokens from our brand guidelines"</span>,
      <span class="hljs-attr">"color"</span>: {
        <span class="hljs-attr">"$description"</span>: <span class="hljs-string">"Our brand's primary color palette"</span>,
        <span class="hljs-attr">"acid green"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#00ff66"</span>
        },
        <span class="hljs-attr">"hot pink"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#dd22cc"</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  <p>Suggested ways tools <em class="rfc2119">MAY</em> use this property are:</p>
  <ul>
  <li>A style guide generator could render a section for each group and use the description as an introductory paragraph</li>
  <li>A GUI tool that lets users browse or select tokens could display this info alongside the corresponding group or as a tooltip</li>
  <li>Export tools could output this as a source code comment</li>
  </ul>
  <div class="issue closed" id="issue-container-number-72"><div role="heading" class="issue-title marker" id="h-issue" aria-level="5"><a href="https://github.com/design-tokens/community-group/issues/72"><span class="issue-number">Issue 72</span></a><span class="issue-label">: Group &amp; file level properties <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a></span></div><div class="">

  <p>Groups may support additional properties like type and description. Should other properties be supported at the group level?</p>
  </div></div>

  </section><section id="type-1"><div class="header-wrapper"><h4 id="x6-1-2-type"><bdi class="secno">6.1.2 </bdi>Type</h4><a class="self-link" href="#type-1" aria-label="Permalink for Section 6.1.2"></a></div>
  <p>Groups <em class="rfc2119">MAY</em> include an optional <code>$type</code> property so a type property does not need to be manually added to every token. <a href="#types">See supported "Types"</a> for more information.</p>
  <p>If a group has a <code>$type</code> property it acts as a default type for any tokens within the group, including ones in nested groups, that do not explicity declare a type via their own <code>$type</code> property. For the full set of rules by which a design token's type is determined, please refer to the <a href="#type-0">design token type property chapter</a>.</p>
  <p>For example:</p>
  <aside class="example" id="example-9"><div class="marker">
      <a class="self-link" href="#example-9">Example<bdi> 9</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"brand"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>,
      <span class="hljs-attr">"color"</span>: {
        <span class="hljs-attr">"acid green"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#00ff66"</span>
        },
        <span class="hljs-attr">"hot pink"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#dd22cc"</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  </section></section><section id="use-cases"><div class="header-wrapper"><h3 id="x6-2-use-cases"><bdi class="secno">6.2 </bdi>Use-cases</h3><a class="self-link" href="#use-cases" aria-label="Permalink for Section 6.2"></a></div>
  <section id="file-authoring-organization"><div class="header-wrapper"><h4 id="x6-2-1-file-authoring-organization"><bdi class="secno">6.2.1 </bdi>File authoring &amp; organization</h4><a class="self-link" href="#file-authoring-organization" aria-label="Permalink for Section 6.2.1"></a></div>
  <p>Groups let token file authors better organize their token files. Related tokens can be nested into groups to align with the team's naming conventions and/or mental model. When manually authoring files, using groups is also less verbose than a flat list of tokens with repeating prefixes.</p>
  <p>For example:</p>
  <aside class="example" id="example-10"><div class="marker">
      <a class="self-link" href="#example-10">Example<bdi> 10</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"brand"</span>: {
      <span class="hljs-attr">"color"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>,
        <span class="hljs-attr">"acid green"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#00ff66"</span>
        },
        <span class="hljs-attr">"hot pink"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#dd22cc"</span>
        }
      },
      <span class="hljs-attr">"typeface"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontFamily"</span>,
        <span class="hljs-attr">"primary"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"Comic Sans MS"</span>
        },
        <span class="hljs-attr">"secondary"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"Times New Roman"</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  <p>...is likely to be more convenient to type and, arguably, easier to read, than:</p>
  <aside class="example" id="example-11"><div class="marker">
      <a class="self-link" href="#example-11">Example<bdi> 11</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"brand-color-acid-green"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#00ff66"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>
    },
    <span class="hljs-attr">"brand-color-hot-pink"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#dd22cc"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>
    },
    <span class="hljs-attr">"brand-typeface-primary"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"Comic Sans MS"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontFamily"</span>
    },
    <span class="hljs-attr">"brand-typeface-secondary"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"Times New Roman"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontFamily"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="gui-tools"><div class="header-wrapper"><h4 id="x6-2-2-gui-tools"><bdi class="secno">6.2.2 </bdi>GUI tools</h4><a class="self-link" href="#gui-tools" aria-label="Permalink for Section 6.2.2"></a></div>
  <p>Tools that let users pick or edit tokens via a GUI <em class="rfc2119">MAY</em> use the grouping structure to display a suitable form of progressive disclosure, such as a collapsible tree view.</p>
  <p><img src="./group-progressive-disclosure.png" alt="Progressive disclosure groups" height="426" width="506"></p>
  </section><section id="export-tools"><div class="header-wrapper"><h4 id="x6-2-3-export-tools"><bdi class="secno">6.2.3 </bdi>Export tools</h4><a class="self-link" href="#export-tools" aria-label="Permalink for Section 6.2.3"></a></div>
  <p>Token names are not guaranteed to be unique within the same file. The same name can be used in different groups. Also, export tools <em class="rfc2119">MAY</em> need to export design tokens in a uniquely identifiable way, such as variables in code. Export tools <em class="rfc2119">SHOULD</em> therefore use design tokens' paths as these <em>are</em> unique within a file.</p>
  <p>For example, a <a data-link-type="dfn" href="#dfn-translation-tool" class="internalDFN" id="ref-for-dfn-translation-tool-4">translation tool</a> like <a href="https://amzn.github.io/style-dictionary/">Style Dictionary</a> might use the following design token file:</p>
  <aside class="example" id="example-12"><div class="marker">
      <a class="self-link" href="#example-12">Example<bdi> 12</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"brand"</span>: {
      <span class="hljs-attr">"color"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>,
        <span class="hljs-attr">"acid green"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#00ff66"</span>
        },
        <span class="hljs-attr">"hot pink"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#dd22cc"</span>
        }
      },
      <span class="hljs-attr">"typeface"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontFamily"</span>,
        <span class="hljs-attr">"primary"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"Comic Sans MS"</span>
        },
        <span class="hljs-attr">"secondary"</span>: {
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"Times New Roman"</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  <p>...and output it as Sass variables like so by concatenating the path to create variable names:</p>
  <aside class="example" id="example-13"><div class="marker">
      <a class="self-link" href="#example-13">Example<bdi> 13</bdi></a>
    </div>

  <pre><code class="scss hljs" aria-busy="false">$brand-color-acid-green: #00ff66;
  $brand-color-hot-pink: #dd22cc;
  $brand-typeface-primary: 'Comic Sans MS';
  $brand-typeface-secondary: 'Times New Roman';
  </code></pre>
  </aside></section></section></section>

      <section id="aliases-references"><div class="header-wrapper"><h2 id="x7-aliases-references"><bdi class="secno">7. </bdi>Aliases / references</h2><a class="self-link" href="#aliases-references" aria-label="Permalink for Section 7."></a></div>
  <p>Instead of having explicit values, tokens can reference the value of another token. To put it another way, a token can be an alias for another token. This spec considers the terms "alias" and "reference" to be synonyms and uses them interchangeably.</p>
  <p>Aliases are useful for:</p>
  <ul>
  <li>Expressing design choices</li>
  <li>Eliminating repetition of values in token files (DRYing up the code)</li>
  </ul>
  <p>For a design token to reference another, its value <em class="rfc2119">MUST</em> be a string containing the period-separated (<code>.</code>) path to the token it's referencing enclosed in curly brackets.</p>
  <p>For example:</p>
  <aside class="example" id="example-14"><div class="marker">
      <a class="self-link" href="#example-14">Example<bdi> 14</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"group name"</span>: {
      <span class="hljs-attr">"token name"</span>: {
        <span class="hljs-attr">"$value"</span>: <span class="hljs-number">1234</span>
      }
    },
    <span class="hljs-attr">"alias name"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"{group name.token name}"</span>
    }
  }
  </code></pre>
  </aside>

  <p>When a tool needs the actual value of a token it <em class="rfc2119">MUST</em> resolve the reference - i.e. lookup the token being referenced and fetch its value. In the above example, the "alias name" token's value would resolve to 1234 because it references the token whose path is <code>{group name.token name}</code> which has the value 1234.</p>
  <p>Tools <em class="rfc2119">SHOULD</em> preserve references and therefore only resolve them whenever the actual value needs to be retrieved. For instance, in a <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-5">design tool</a>, changes to the value of a token being referenced by aliases <em class="rfc2119">SHOULD</em> be reflected wherever those aliases are being used.</p>
  <p>Aliases <em class="rfc2119">MAY</em> reference other aliases. In this case, tools <em class="rfc2119">MUST</em> follow each reference until they find a token with an explicit value. Circular references are not allowed. If a design token file contains circular references, then the value of all tokens in that chain is unknown and an appropriate error or warning message <em class="rfc2119">SHOULD</em> be displayed to the user.</p>
  <div class="note" id="issue-container-generatedID-5"><div role="heading" class="ednote-title marker" id="h-ednote-5" aria-level="3"><span>Editor's note</span><span class="issue-label">: JSON Pointer syntax</span></div><p class="">
    The format editors are currently researching JSON Pointer syntax to inform the exact syntax for aliases in tokens. <a href="https://datatracker.ietf.org/doc/html/rfc6901#section-5">https://datatracker.ietf.org/doc/html/rfc6901#section-5</a>
  </p></div></section>

      <section id="types"><div class="header-wrapper"><h2 id="x8-types"><bdi class="secno">8. </bdi>Types</h2><a class="self-link" href="#types" aria-label="Permalink for Section 8."></a></div>
  <p>Many tools need to know what kind of value a given token represents to process it sensibly. Export tools <em class="rfc2119">MAY</em> need to convert or format tokens differently depending on their type. <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-6">Design tools</a> <em class="rfc2119">MAY</em> present the user with different kinds of input when editing tokens of a certain type (such as color picker, slider, text input, etc.). Style guide generators <em class="rfc2119">MAY</em> use different kinds of previews for different types of tokens.</p>
  <p>Since design token files are JSON files, all the basic JSON types are available:</p>
  <ul>
  <li>String</li>
  <li>Number</li>
  <li>Object</li>
  <li>Array</li>
  <li>Boolean</li>
  <li>Null</li>
  </ul>
  <p>Additionally, this spec defines a number of more design-focused types. To set a token to one of these types, it <em class="rfc2119">MUST</em> either have a <code>$type</code> property specifying the chosen type, inherit a type from one of its parent groups, or be an alias of a token that has the desired type. Furthermore, that token's value <em class="rfc2119">MUST</em> then follow rules and syntax for the chosen type as defined by this spec.</p>
  <p>If no explicit type has been set for a token, tools <em class="rfc2119">MUST</em> treat values as one of the basic JSON types and not attempt to infer any other type from the value.</p>
  <p>If an explicit type is set, but the value does not match the expected syntax then that token is invalid and an appropriate error <em class="rfc2119">SHOULD</em> be displayed to the user. To put it another way, the <code>$type</code> property is a declaration of what kind of values are permissible for the token. (This is similar to typing in programming languages like Java or TypeScript, where a value not compatible with the declared type causes a compilation error).</p>
  <section id="color"><div class="header-wrapper"><h3 id="x8-1-color"><bdi class="secno">8.1 </bdi>Color</h3><a class="self-link" href="#color" aria-label="Permalink for Section 8.1"></a></div>
  <p>Represents a 24bit RGB or 24+8bit RGBA color in the sRGB color space. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>color</code>. The value <em class="rfc2119">MUST</em> be a string containing a hex triplet/quartet including the preceding <code>#</code> character. To support other color spaces, such as HSL, export tools <em class="rfc2119">SHOULD</em> convert color tokens to the equivalent value as needed.</p>
  <p>For example, initially the color tokens <em class="rfc2119">MAY</em> be defined as such:</p>
  <aside class="example" id="example-15"><div class="marker">
      <a class="self-link" href="#example-15">Example<bdi> 15</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Majestic magenta"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#ff00ff"</span>,
      <span class="hljs-attr">"$ype"</span>: <span class="hljs-string">"color"</span>
    },
    <span class="hljs-attr">"Translucent shadow"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#00000088"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>
    }
  }
  </code></pre>
  </aside>

  <p>Then, the output from a tool's conversion to HSL(A) <em class="rfc2119">MAY</em> look something like:</p>
  <aside class="example" id="example-16"><div class="marker">
      <a class="self-link" href="#example-16">Example<bdi> 16</bdi></a>
    </div>

  <pre><code class="scss hljs" aria-busy="false">// colors-hex.scss
  $majestic-magenta: #ff00ff;
  $translucent-shadow: #00000080;

  // colors-hsl.scss
  $majestic-magenta: hsl(300, 100%, 50%);
  $translucent-shadow: hsla(300, 100%, 50%, 0.5);
  </code></pre>
  </aside>

  </section><section id="dimension"><div class="header-wrapper"><h3 id="x8-2-dimension"><bdi class="secno">8.2 </bdi>Dimension</h3><a class="self-link" href="#dimension" aria-label="Permalink for Section 8.2"></a></div>
  <p>Represents an amount of distance in a single dimension in the UI, such as a position, width, height, radius, or thickness. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>dimension</code>. The value must be a string containing a number (either integer or floating-point) followed by either a "px" or "rem" unit (future spec iterations may add support for additional units).</p>
  <p>For example:</p>
  <aside class="example" id="example-17"><div class="marker">
      <a class="self-link" href="#example-17">Example<bdi> 17</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"spacingStack1X"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"0.25rem"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"dimension"</span>
    }
  }
  </code></pre>
  </aside>

  <p>The "px" and "rem" units are to be interpreted the same way they are in CSS:</p>
  <ul>
  <li><strong>px</strong>: Represents an idealized pixel on the viewport. The equivalent in Android is dp and iOS is pt. Export tools <em class="rfc2119">SHOULD</em> therefore convert to these or other equivalent units as needed.</li>
  <li><strong>rem</strong>: Represents a multiple of the system's default font size (which <em class="rfc2119">MAY</em> be configurable by the user). 1rem is 100% of the default font size. The equivalent of 1rem on Android is 16sp. Not all platforms have an equivalent to rem, so export tools <em class="rfc2119">MAY</em> need to do a lossy conversion to a fixed px size by assuming a default font size (usually 16px) for such platforms.</li>
  </ul>
  </section><section id="font-family"><div class="header-wrapper"><h3 id="x8-3-font-family"><bdi class="secno">8.3 </bdi>Font family</h3><a class="self-link" href="#font-family" aria-label="Permalink for Section 8.3"></a></div>
  <div class="issue" id="issue-container-number-53"><div role="heading" class="issue-title marker" id="h-issue-0" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/53"><span class="issue-number">Issue 53</span></a><span class="issue-label">: Type: font family <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Feedback%2FReview%22" style="background-color: rgb(83, 25, 231); color: rgb(255, 255, 255);" aria-label="GitHub label: Needs Feedback/Review">Needs Feedback/Review</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Reviewed+by+editors%22" style="background-color: rgb(112, 105, 34); color: rgb(255, 255, 255);" aria-label="GitHub label: Reviewed by editors">Reviewed by editors</a></span></div><div class="">

  <p>A naive approach like the one below may be appropriate for the first stage of the specification, but this could be more complicated than it seems due to platform/OS/browser restrictions.</p>
  </div></div>

  <p>Represents a font name or an array of font names (ordered from most to least preferred). The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>fontFamily</code>. The value <em class="rfc2119">MUST</em> either be a string value containing a single font name or an array of strings, each being a single font name.</p>
  <p>For example:</p>
  <aside class="example" id="example-18"><div class="marker">
      <a class="self-link" href="#example-18">Example<bdi> 18</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Primary font"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"Comic Sans MS"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontFamily"</span>
    },
    <span class="hljs-attr">"Body font"</span>: {
      <span class="hljs-attr">"$value"</span>: [<span class="hljs-string">"Helvetica"</span>, <span class="hljs-string">"Arial"</span>],
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontFamily"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="font-weight"><div class="header-wrapper"><h3 id="x8-4-font-weight"><bdi class="secno">8.4 </bdi>Font weight</h3><a class="self-link" href="#font-weight" aria-label="Permalink for Section 8.4"></a></div>
  <p>Represents a font weight. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>fontWeight</code>. The value must either be a number value in the range [1, 1000] or one of the pre-defined string values defined in the table below.</p>
  <p>Lower numbers represent lighter weights, and higher numbers represent thicker weights, as per the <a href="https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxistag_wght">OpenType <code>wght</code> tag specification</a>. The pre-defined string values are aliases for specific numeric values. For example <code>100</code>, <code>"thin"</code> and <code>"hairline"</code> are all the exact same value.</p>
  <table>
  <thead>
  <tr>
  <th>numeric value</th>
  <th>string value aliases</th>
  </tr>
  </thead>
  <tbody><tr>
  <td><code>100</code></td>
  <td><code>thin</code>, <code>hairline</code></td>
  </tr>
  <tr>
  <td><code>200</code></td>
  <td><code>extra-light</code>, <code>ultra-light</code></td>
  </tr>
  <tr>
  <td><code>300</code></td>
  <td><code>light</code></td>
  </tr>
  <tr>
  <td><code>400</code></td>
  <td><code>normal</code>, <code>regular</code>, <code>book</code></td>
  </tr>
  <tr>
  <td><code>500</code></td>
  <td><code>medium</code></td>
  </tr>
  <tr>
  <td><code>600</code></td>
  <td><code>semi-bold</code>, <code>demi-bold</code></td>
  </tr>
  <tr>
  <td><code>700</code></td>
  <td><code>bold</code></td>
  </tr>
  <tr>
  <td><code>800</code></td>
  <td><code>extra-bold</code>, <code>ultra-bold</code></td>
  </tr>
  <tr>
  <td><code>900</code></td>
  <td><code>black</code>, <code>heavy</code></td>
  </tr>
  <tr>
  <td><code>950</code></td>
  <td><code>extra-black</code>, <code>ultra-black</code></td>
  </tr>
  </tbody></table>
  <p>Number values outside of the [1, 1000] range and any other string values, including ones that differ only in case, are invalid and <em class="rfc2119">MUST</em> be rejected by tools.</p>
  <p>Example:</p>
  <aside class="example" id="example-19"><div class="marker">
      <a class="self-link" href="#example-19">Example<bdi> 19</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"font-weight-default"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-number">350</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontWeight"</span>
    },
    <span class="hljs-attr">"font-weight-thick"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"extra-bold"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"fontWeight"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="duration"><div class="header-wrapper"><h3 id="x8-5-duration"><bdi class="secno">8.5 </bdi>Duration</h3><a class="self-link" href="#duration" aria-label="Permalink for Section 8.5"></a></div>
  <p>Represents the length of time in milliseconds an animation or animation cycle takes to complete, such as 200 milliseconds. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>duration</code>. The value <em class="rfc2119">MUST</em> be a string containing a number (either integer or floating-point) followed by an "ms" unit. A millisecond is a unit of time equal to one thousandth of a second.</p>
  <p>For example:</p>
  <aside class="example" id="example-20"><div class="marker">
      <a class="self-link" href="#example-20">Example<bdi> 20</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Duration-100"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"100ms"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"duration"</span>
    },
    <span class="hljs-attr">"Duration-200"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"200ms"</span>,
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"duration"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="cubic-bezier"><div class="header-wrapper"><h3 id="x8-6-cubic-bezier"><bdi class="secno">8.6 </bdi>Cubic Bézier</h3><a class="self-link" href="#cubic-bezier" aria-label="Permalink for Section 8.6"></a></div>
  <p>Represents how the value of an animated property progresses towards completion over the duration of an animation, effectively creating visual effects such as acceleration, deceleration, and bounce. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>cubicBezier</code>. The value <em class="rfc2119">MUST</em> be an array containing four numbers. These numbers represent two points (P1, P2) with one x coordinate and one y coordinate each [P1x, P1y, P2x, P2y]. The y coordinates of P1 and P2 can be any real number in the range [-∞, ∞], but the x coordinates are restricted to the range [0, 1].</p>
  <p>For example:</p>
  <aside class="example" id="example-21"><div class="marker">
      <a class="self-link" href="#example-21">Example<bdi> 21</bdi></a>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"Accelerate"</span>: {
      <span class="hljs-attr">"$value"</span>: [<span class="hljs-number">0.5</span>, <span class="hljs-number">0</span>, <span class="hljs-number">1</span>, <span class="hljs-number">1</span>],
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"cubicBezier"</span>
    },
    <span class="hljs-attr">"Decelerate"</span>: {
      <span class="hljs-attr">"$value"</span>: [<span class="hljs-number">0</span>, <span class="hljs-number">0</span>, <span class="hljs-number">0.5</span>, <span class="hljs-number">1</span>],
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"cubicBezier"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section class="informative" id="additional-types"><div class="header-wrapper"><h3 id="x8-7-additional-types"><bdi class="secno">8.7 </bdi>Additional types</h3><a class="self-link" href="#additional-types" aria-label="Permalink for Section 8.7"></a></div><p><em>This section is non-normative.</em></p>


  <p>Types still to be documented here are likely to include:</p>
  <ul>
  <li><strong>Font style:</strong> might be an enum of allowed values like ("normal", "italic"...)</li>
  <li><strong>Percentage/ratio:</strong> e.g. for opacity values, relative dimensions, aspect ratios, etc.<ul>
  <li>Not 100% sure about this since these are really "just" numbers. An alternative might be that we expand the permitted syntax for the "number" type, so for example "1:2", "50%" and 0.5 are all equivalent. People can then use whichever syntax they like best for a given token.</li>
  </ul>
  </li>
  <li><strong>File:</strong> for assets - might just be a relative file path / URL (or should we let people also express the mime-type?)</li>
  </ul>
  </section></section>

      <section id="composite-types"><div class="header-wrapper"><h2 id="x9-composite-types"><bdi class="secno">9. </bdi>Composite types</h2><a class="self-link" href="#composite-types" aria-label="Permalink for Section 9."></a></div>
  <p>The types defined in the previous chapters such as color and dimension all have singular values. For example, the value of a color token is <em>one</em> color. However, there are other aspects of UI designs that are a combination of multiple values. For instance, a shadow style is a combination of a color, X &amp; Y offsets, a blur radius and a spread radius.</p>
  <p>Every shadow style has the exact same parts (color, X &amp; Y offsets, etc.), but their respective values will differ. Furthermore, each part's value (which is also known as a "sub-value") is always of the same type. A shadow's color must always be a <a href="#color">color</a> value, its X offset must always be a <a href="#dimension">dimension</a> value, and so on. Shadow styles are therefore combinations of values <em>that follow a pre-defined structure</em>. In other words, shadow styles are themselves a type. Types like this are called <strong>composite types</strong>.</p>
  <p>Specifically, a composite type has the following characteristics:</p>
  <ul>
  <li>Its value is an object or array, potentially containing nested objects or arrays, following a pre-defined structure where the properties of the (nested) object(s) or the elements of the (nested) arrays are sub-values.</li>
  <li>Sub-values may be explicit values (e.g. <code>"#ff0000"</code>) or references to other design tokens that have sub-value's type (e.g. <code>"{some.other.token}"</code>).</li>
  </ul>
  <p>A design token whose type happens to be a composite type is sometimes also called a composite (design) token. Besides their type, there is nothing special about composite tokens. They can have all the other additional properties like <a href="#description"><code>$description</code></a> or <a href="#extensions"><code>$extensions</code></a>. They can also be referenced by other design tokens.</p>
  <aside class="example" id="example-composite-token-example"><div class="marker">
      <a class="self-link" href="#example-composite-token-example">Example<bdi> 22</bdi></a><span class="example-title">: Composite token example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"shadow-token"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"shadow"</span>,
      <span class="hljs-attr">"$value"</span>: {
        <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#00000088"</span>,
        <span class="hljs-attr">"offsetX"</span>: <span class="hljs-string">"0.5rem"</span>,
        <span class="hljs-attr">"offsetY"</span>: <span class="hljs-string">"0.5rem"</span>,
        <span class="hljs-attr">"blur"</span>: <span class="hljs-string">"1.5rem"</span>,
        <span class="hljs-attr">"spread"</span>: <span class="hljs-string">"0rem"</span>
      }
    }
  }
  </code></pre>
  </aside>

  <aside class="example" id="example-advanced-composite-token-example"><div class="marker">
      <a class="self-link" href="#example-advanced-composite-token-example">Example<bdi> 23</bdi></a><span class="example-title">: Advanced composite token example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"space"</span>: {
      <span class="hljs-attr">"small"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"dimension"</span>,
        <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"0.5rem"</span>
      }
    },

    <span class="hljs-attr">"color"</span>: {
      <span class="hljs-attr">"shadow-050"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>,
        <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#00000088"</span>
      }
    },

    <span class="hljs-attr">"shadow"</span>: {
      <span class="hljs-attr">"medium"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"shadow"</span>,
        <span class="hljs-attr">"$description"</span>: <span class="hljs-string">"A composite token where some sub-values are references to tokens that have the correct type and others are explicit values"</span>,
        <span class="hljs-attr">"$value"</span>: {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"{color.shadow-050}"</span>,
          <span class="hljs-attr">"offsetX"</span>: <span class="hljs-string">"{space.small}"</span>,
          <span class="hljs-attr">"offsetY"</span>: <span class="hljs-string">"{space.small}"</span>,
          <span class="hljs-attr">"blur"</span>: <span class="hljs-string">"1.5rem"</span>,
          <span class="hljs-attr">"spread"</span>: <span class="hljs-string">"0rem"</span>
        }
      }
    },

    <span class="hljs-attr">"component"</span>: {
      <span class="hljs-attr">"card"</span>: {
        <span class="hljs-attr">"box-shadow"</span>: {
          <span class="hljs-attr">"$description"</span>: <span class="hljs-string">"This token is an alias for the composite token {shadow.medium}"</span>,
          <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"{shadow.medium}"</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  <section id="groups-versus-composite-tokens"><div class="header-wrapper"><h3 id="x9-1-groups-versus-composite-tokens"><bdi class="secno">9.1 </bdi>Groups versus composite tokens</h3><a class="self-link" href="#groups-versus-composite-tokens" aria-label="Permalink for Section 9.1"></a></div>
  <p>At first glance, groups and composite tokens might look very similar. However, they are intended to solve different problems and therefore have some important differences:</p>
  <ul>
  <li><strong><a href="#groups">Groups</a></strong> are for arbitrarily grouping tokens for the purposes of naming and/or organization.<ul>
  <li>They impose no rules or restrictions on how many tokens or nested groups you put within them, what they are called, or what the types of the tokens within should be. As such, tools <em class="rfc2119">MUST NOT</em> try to infer any special meaning or typing of tokens based on a group they happen to be in.</li>
  <li>Different design systems are likely to group their tokens differently.</li>
  <li>You can think of groups as containers that exist "outside" of design tokens.</li>
  </ul>
  </li>
  <li><strong>Composite tokens</strong> are individual design tokens whose values are made up of several sub-values.<ul>
  <li>Since they are design tokens, they can be referenced by other design tokens. This is not true for groups.</li>
  <li>Their type must be one of the composite types defined in this specification. Therefore their names and types of their sub-values are pre-defined. Adding additional sub-values or setting values that don't have the correct type make the composite token invalid.</li>
  <li>Tools <em class="rfc2119">MAY</em> provide specialized functionality for composite tokens. For example, a <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-7">design tool</a> may let the user pick from a list of all available shadow tokens when applying a drop shadow effect to an element.</li>
  </ul>
  </li>
  </ul>
  </section><section id="stroke-style"><div class="header-wrapper"><h3 id="x9-2-stroke-style"><bdi class="secno">9.2 </bdi>Stroke style</h3><a class="self-link" href="#stroke-style" aria-label="Permalink for Section 9.2"></a></div>
  <p>Represents the style applied to lines or borders. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>strokeStyle</code>. The value <em class="rfc2119">MUST</em> be either:</p>
  <ul>
  <li>a string value as defined in the corresponding section below, or</li>
  <li>an object value as defined in the corresponding section below</li>
  </ul>
  <div class="issue" id="issue-container-number-98"><div role="heading" class="issue-title marker" id="h-issue-1" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/98"><span class="issue-number">Issue 98</span></a><span class="issue-label">: Stroke style type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Feedback%2FReview%22" style="background-color: rgb(83, 25, 231); color: rgb(255, 255, 255);" aria-label="GitHub label: Needs Feedback/Review">Needs Feedback/Review</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a></span></div><div class="">
    Is the current specification for stroke styles fit for purpose? Does it need more sub-values (e.g. equivalents to SVG's <code>stroke-linejoin</code>, <code>stroke-miterlimit</code> and <code>stroke-dashoffset</code> attributes)?
  </div></div>

  <section id="string-value"><div class="header-wrapper"><h4 id="x9-2-1-string-value"><bdi class="secno">9.2.1 </bdi>String value</h4><a class="self-link" href="#string-value" aria-label="Permalink for Section 9.2.1"></a></div>
  <p>String stroke style values <em class="rfc2119">MUST</em> be set to one of the following, pre-defined values:</p>
  <ul>
  <li><code>solid</code></li>
  <li><code>dashed</code></li>
  <li><code>dotted</code></li>
  <li><code>double</code></li>
  <li><code>groove</code></li>
  <li><code>ridge</code></li>
  <li><code>outset</code></li>
  <li><code>inset</code></li>
  </ul>
  <p>These values have the same meaning as the equivalent <a href="https://drafts.csswg.org/css-backgrounds/#typedef-line-style">"line style" values in CSS</a>. As per the CSS spec, their exact rendering is therefore implementation specific. For example, the length of dashes and gaps in the <code>dashed</code> style may vary between different tools.</p>
  <aside class="example" id="example-string-stroke-style-example"><div class="marker">
      <a class="self-link" href="#example-string-stroke-style-example">Example<bdi> 24</bdi></a><span class="example-title">: String stroke style example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"focus-ring-style"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"strokeStyle"</span>,
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"dashed"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="object-value"><div class="header-wrapper"><h4 id="x9-2-2-object-value"><bdi class="secno">9.2.2 </bdi>Object value</h4><a class="self-link" href="#object-value" aria-label="Permalink for Section 9.2.2"></a></div>
  <p>Object stroke style values <em class="rfc2119">MUST</em> have the following properties:</p>
  <ul>
  <li><code>dashArray</code>: An array of <a href="#dimension">dimension values</a> and/or references to dimension tokens, which specify the lengths of alternating dashes and gaps. If an odd number of values is provided, then the list of values is repeated to yield an even number of values.</li>
  <li><code>lineCap</code>: One of the following pre-defined string values: <code>"round"</code>, <code>"butt"</code> or <code>"square"</code>. These values have the same meaning as those of <a href="https://www.w3.org/TR/SVG11/painting.html#StrokeLinecapProperty">the <code>stroke-linecap</code> attribute in SVG</a>.</li>
  </ul>
  <aside class="example" id="example-object-stroke-style-example"><div class="marker">
      <a class="self-link" href="#example-object-stroke-style-example">Example<bdi> 25</bdi></a><span class="example-title">: Object stroke style example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"alert-border-style"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"strokeStyle"</span>,
      <span class="hljs-attr">"$value"</span>: {
        <span class="hljs-attr">"dashArray"</span>: [<span class="hljs-string">"0.5rem"</span>, <span class="hljs-string">"0.25rem"</span>],
        <span class="hljs-attr">"lineCap"</span>: <span class="hljs-string">"round"</span>
      }
    }
  }
  </code></pre>
  </aside>

  <aside class="example" id="example-stroke-style-obj-ref"><div class="marker">
      <a class="self-link" href="#example-stroke-style-obj-ref">Example<bdi> 26</bdi></a><span class="example-title">: Object stroke style example using references</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"notification-border-style"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"strokeStyle"</span>,
      <span class="hljs-attr">"$value"</span>: {
        <span class="hljs-attr">"dashArray"</span>: [<span class="hljs-string">"{dash-length-medium}"</span>, <span class="hljs-string">"0.25rem"</span>],
        <span class="hljs-attr">"lineCap"</span>: <span class="hljs-string">"butt"</span>
      }
    },

    <span class="hljs-attr">"dash-length-medium"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"dimension"</span>,
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"10px"</span>
    }
  }
  </code></pre>
  </aside>

  </section><section id="fallbacks"><div class="header-wrapper"><h4 id="x9-2-3-fallbacks"><bdi class="secno">9.2.3 </bdi>Fallbacks</h4><a class="self-link" href="#fallbacks" aria-label="Permalink for Section 9.2.3"></a></div>
  <p>The string and object values are mutually exclusive means of expressing stroke styles. For example, some of the string values like <code>inset</code> or <code>groove</code> cannot be expressed in terms of a <code>dashArray</code> and <code>lineCap</code> as they require some implementation-specific means of lightening or darkening the <em>color</em> for portions of a border or outline. Conversely, a precisely defined combination of <code>dashArray</code> and <code>lineCap</code> sub-values is not guaranteed to produce the same visual result as the <code>dashed</code> or <code>dotted</code> keywords as they are implementation-specific.</p>
  <p>Furthermore, some tools and platforms may not support the full range of stroke styles that design tokens of this type can represent. When displaying or exporting a <code>strokeStyle</code> token whose value they don't natively support, they should therefore fallback to the closest approximation that they do support.</p>
  <p>The specifics of how a "closest approximation" is chosen are implementation-specific. However, the following examples illustrate what fallbacks tools <em class="rfc2119">MAY</em> use in some scenarios.</p>
  <aside class="example" id="example-fallback-for-object-stroke-style"><div class="marker">
      <a class="self-link" href="#example-fallback-for-object-stroke-style">Example<bdi> 27</bdi></a><span class="example-title">: Fallback for object stroke style</span>
    </div>

  <p>CSS does not allow detailed control of the dash pattern or line caps on dashed borders. So, a tool exporting the <code>"notification-border-style"</code> design token from the <a href="#example-stroke-style-obj-ref">example in the previous section</a>, might use the CSS <code>dashed</code> line style as a fallback:</p>
  <pre><code class="css hljs" aria-busy="false"><span class="hljs-selector-pseudo">:root</span> {
    --notification-<span class="hljs-attribute">border-style</span>: dashed;
  }
  </code></pre>
  </aside>

  <aside class="example" id="example-fallback-for-string-stroke-style"><div class="marker">
      <a class="self-link" href="#example-fallback-for-string-stroke-style">Example<bdi> 28</bdi></a><span class="example-title">: Fallback for string stroke style</span>
    </div>

  <p>Some <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-8">design tools</a> like Figma don't support inset, outset or double style lines. When a user applies a <code>stroke-style</code> token with those values, such tools might therefore fallback to displaying a solid line instead.</p>
  </aside>

  </section></section><section id="border"><div class="header-wrapper"><h3 id="x9-3-border"><bdi class="secno">9.3 </bdi>Border</h3><a class="self-link" href="#border" aria-label="Permalink for Section 9.3"></a></div>
  <p>Represents a border style. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>border</code>. The value <em class="rfc2119">MUST</em> be an object with the following properties:</p>
  <ul>
  <li><code>color</code>: The color of the border. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#color">color value</a> or a reference to a color token.</li>
  <li><code>width</code>: The width or thickness of the border. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#dimension">dimension value</a> or a reference to a dimension token.</li>
  <li><code>style</code>: The border's style. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#stroke-style">stroke style value</a> or a reference to a stroke style token.</li>
  </ul>
  <aside class="example" id="example-border-composite-token-examples"><div class="marker">
      <a class="self-link" href="#example-border-composite-token-examples">Example<bdi> 29</bdi></a><span class="example-title">: Border composite token examples</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"border"</span>: {
      <span class="hljs-attr">"heavy"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"border"</span>,
        <span class="hljs-attr">"$value"</span>: {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#36363600"</span>,
          <span class="hljs-attr">"width"</span>: <span class="hljs-string">"3px"</span>,
          <span class="hljs-attr">"style"</span>: <span class="hljs-string">"solid"</span>
        }
      },
      <span class="hljs-attr">"focusring"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"border"</span>,
        <span class="hljs-attr">"$value"</span>: {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"{color.focusring}"</span>,
          <span class="hljs-attr">"width"</span>: <span class="hljs-string">"1px"</span>,
          <span class="hljs-attr">"style"</span>: {
            <span class="hljs-attr">"dashArray"</span>: [<span class="hljs-string">"0.5rem"</span>, <span class="hljs-string">"0.25rem"</span>],
            <span class="hljs-attr">"lineCap"</span>: <span class="hljs-string">"round"</span>
          }
        }
      }
    }
  }
  </code></pre>
  </aside>

  <div class="issue" id="issue-container-number-99"><div role="heading" class="issue-title marker" id="h-issue-2" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/99"><span class="issue-number">Issue 99</span></a><span class="issue-label">: Border type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Feedback%2FReview%22" style="background-color: rgb(83, 25, 231); color: rgb(255, 255, 255);" aria-label="GitHub label: Needs Feedback/Review">Needs Feedback/Review</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a></span></div><div class="">
    Is the current specification for borders fit for purpose? Does it need more sub-values to account for features like outset, border images, multiple borders, etc. that some platforms and <a data-link-type="dfn" href="#dfn-design-tool" class="internalDFN" id="ref-for-dfn-design-tool-9">design tools</a> have?
  </div></div>

  </section><section id="transition"><div class="header-wrapper"><h3 id="x9-4-transition"><bdi class="secno">9.4 </bdi>Transition</h3><a class="self-link" href="#transition" aria-label="Permalink for Section 9.4"></a></div>
  <p>Represents a animated transition between two states. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>transition</code>. The value <em class="rfc2119">MUST</em> be an object with the following properties:</p>
  <ul>
  <li><code>duration</code>: The duration of the transition. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#duration">duration</a> value or a reference to a duration token.</li>
  <li><code>delay</code>: The time to wait before the transition begins. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#duration">duration</a> value or a reference to a duration token.</li>
  <li><code>timingFunction</code>: The timing function of the transition. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#cubic-bezier">cubic Bézier</a> value or a reference to a cubic Bézier token.</li>
  </ul>
  <aside class="example" id="example-transition-composite-token-examples"><div class="marker">
      <a class="self-link" href="#example-transition-composite-token-examples">Example<bdi> 30</bdi></a><span class="example-title">: Transition composite token examples</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"transition"</span>: {
      <span class="hljs-attr">"emphasis"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"transition"</span>,
        <span class="hljs-attr">"$value"</span>: {
          <span class="hljs-attr">"duration"</span>: <span class="hljs-string">"200ms"</span>,
          <span class="hljs-attr">"delay"</span>: <span class="hljs-string">"0ms"</span>,
          <span class="hljs-attr">"timingFunction"</span>: [<span class="hljs-number">0.5</span>, <span class="hljs-number">0</span>, <span class="hljs-number">1</span>, <span class="hljs-number">1</span>]
        }
      }
    }
  }
  </code></pre>
  </aside>

  <div class="issue" id="issue-container-number-103"><div role="heading" class="issue-title marker" id="h-issue-3" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/103"><span class="issue-number">Issue 103</span></a><span class="issue-label">: Transition type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Feedback%2FReview%22" style="background-color: rgb(83, 25, 231); color: rgb(255, 255, 255);" aria-label="GitHub label: Needs Feedback/Review">Needs Feedback/Review</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-animation%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-animation">dtcg-animation</a></span></div><div class="">
    Is the current specification for transitions fit for purpose? Are these transitions parameters by themselves useful considering that they don't let you specify what aspect of a UI is being transitioned and what the start and end states are?
  </div></div>

  </section><section id="shadow"><div class="header-wrapper"><h3 id="x9-5-shadow"><bdi class="secno">9.5 </bdi>Shadow</h3><a class="self-link" href="#shadow" aria-label="Permalink for Section 9.5"></a></div>
  <p>Represents a shadow style. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>shadow</code>. The value must be an object with the following properties:</p>
  <ul>
  <li><code>color</code>: The color of the shadow. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#color">color value</a> or a reference to a color token.</li>
  <li><code>offsetX</code>: The horizontal offset that shadow has from the element it is applied to. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#dimension">dimension value</a> or a reference to a dimension token.</li>
  <li><code>offsetY</code>: The vertical offset that shadow has from the element it is applied to. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#dimension">dimension value</a> or a reference to a dimension token.</li>
  <li><code>blur</code>: The blur radius that is applied to the shadow. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#dimension">dimension value</a> or a reference to a dimension token.</li>
  <li><code>spread</code>: The amount by which to expand or contract the shadow. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#dimension">dimension value</a> or a reference to a dimension token.</li>
  </ul>
  <aside class="example" id="example-shadow-token-example"><div class="marker">
      <a class="self-link" href="#example-shadow-token-example">Example<bdi> 31</bdi></a><span class="example-title">: Shadow token example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"shadow-token"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"shadow"</span>,
      <span class="hljs-attr">"$value"</span>: {
        <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#00000088"</span>,
        <span class="hljs-attr">"offsetX"</span>: <span class="hljs-string">"0.5rem"</span>,
        <span class="hljs-attr">"offsetY"</span>: <span class="hljs-string">"0.5rem"</span>,
        <span class="hljs-attr">"blur"</span>: <span class="hljs-string">"1.5rem"</span>,
        <span class="hljs-attr">"spread"</span>: <span class="hljs-string">"0rem"</span>
      }
    }
  }
  </code></pre>
  </aside>

  <div class="issue" id="issue-container-number-100"><div role="heading" class="issue-title marker" id="h-issue-4" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/100"><span class="issue-number">Issue 100</span></a><span class="issue-label">: Shadow type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Feedback%2FReview%22" style="background-color: rgb(83, 25, 231); color: rgb(255, 255, 255);" aria-label="GitHub label: Needs Feedback/Review">Needs Feedback/Review</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a></span></div><div class="">
    Is the current specification for shadows fit for purpose? Does it need to support multiple shadows, as some tools and platforms do?
  </div></div>

  </section><section id="gradient"><div class="header-wrapper"><h3 id="x9-6-gradient"><bdi class="secno">9.6 </bdi>Gradient</h3><a class="self-link" href="#gradient" aria-label="Permalink for Section 9.6"></a></div>
  <p>Represents a color gradient. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>gradient</code>. The value <em class="rfc2119">MUST</em> be an array of objects representing gradient stops that have the following structure:</p>
  <ul>
  <li><code>color</code>: The color value at the stop's position on the gradient. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#color">color value</a> or a reference to a color token.</li>
  <li><code>position</code>: The position of the stop along the gradient's axis. The value of this property <em class="rfc2119">MUST</em> be a valid number value or reference to a number token. The number values must be in the range [0, 1], where 0 represents the start position of the gradient's axis and 1 the end position. If a number value outside of that range is given, it <em class="rfc2119">MUST</em> be considered as if it were clamped to the range [0, 1]. For example, a value of 42 should be treated as if it were 1, i.e. the end position of the gradient axis. Similarly, a value of -99 should be treated as if it were 0, i.e. the start position of the gradient axis.</li>
  </ul>
  <p>If there are no stops at the very beginning or end of the gradient axis (i.e. with <code>position</code> 0 or 1, respectively), then the color from the stop closest to each end should be extended to that end of the axis.</p>
  <aside class="example" id="example-gradient-token-example"><div class="marker">
      <a class="self-link" href="#example-gradient-token-example">Example<bdi> 32</bdi></a><span class="example-title">: Gradient token example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"blue-to-red"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"gradient"</span>,
      <span class="hljs-attr">"$value"</span>: [
        {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#0000ff"</span>,
          <span class="hljs-attr">"position"</span>: <span class="hljs-number">0</span>
        },
        {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#ff0000"</span>,
          <span class="hljs-attr">"position"</span>: <span class="hljs-number">1</span>
        }
      ]
    }
  }
  </code></pre>
  <p>Describes a gradient that goes from blue to red:</p>
  <div style="height: 2rem; background: linear-gradient(90deg, #0000ff, #ff0000);"></div>

  </aside>

  <aside class="example" id="example-gradient-token-with-omitted-start-stop-example"><div class="marker">
      <a class="self-link" href="#example-gradient-token-with-omitted-start-stop-example">Example<bdi> 33</bdi></a><span class="example-title">: Gradient token with omitted start stop example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"mostly-yellow"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"gradient"</span>,
      <span class="hljs-attr">"$value"</span>: [
        {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#ffff00"</span>,
          <span class="hljs-attr">"position"</span>: <span class="hljs-number">0.666</span>
        },
        {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#ff0000"</span>,
          <span class="hljs-attr">"position"</span>: <span class="hljs-number">1</span>
        }
      ]
    }
  }
  </code></pre>
  <p>Describes a gradient that is solid yellow for the first 2/3 and then fades to red:</p>
  <div style="height: 2rem; background: linear-gradient(90deg, #ffff00 66.6%, #ff0000);"></div>

  </aside>

  <aside class="example" id="example-gradient-token-using-references-example"><div class="marker">
      <a class="self-link" href="#example-gradient-token-using-references-example">Example<bdi> 34</bdi></a><span class="example-title">: Gradient token using references example</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"brand-primary"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"color"</span>,
      <span class="hljs-attr">"$value"</span>: <span class="hljs-string">"#99ff66"</span>
    },

    <span class="hljs-attr">"position-end"</span>: {
      <span class="hljs-attr">"$value"</span>: <span class="hljs-number">1</span>
    },

    <span class="hljs-attr">"brand-in-the-middle"</span>: {
      <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"gradient"</span>,
      <span class="hljs-attr">"$value"</span>: [
        {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#000000"</span>,
          <span class="hljs-attr">"position"</span>: <span class="hljs-number">0</span>
        },
        {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"{brand-primary}"</span>,
          <span class="hljs-attr">"position"</span>: <span class="hljs-number">0.5</span>
        },
        {
          <span class="hljs-attr">"color"</span>: <span class="hljs-string">"#000000"</span>,
          <span class="hljs-attr">"position"</span>: <span class="hljs-string">"{position-end}"</span>
        }
      ]
    }
  }
  </code></pre>
  <p>Describes a color token called "brand-primary", which is referenced as the mid-point of a gradient is black at either end.</p>
  <div style="height: 2rem; background: linear-gradient(90deg, #000000, #99ff66, #000000);"></div>

  </aside>

  <div class="issue" id="issue-container-number-101"><div role="heading" class="issue-title marker" id="h-issue-5" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/101"><span class="issue-number">Issue 101</span></a><span class="issue-label">: Gradient type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Feedback%2FReview%22" style="background-color: rgb(83, 25, 231); color: rgb(255, 255, 255);" aria-label="GitHub label: Needs Feedback/Review">Needs Feedback/Review</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a></span></div><div class="">
    Is the current specification for gradients fit for purpose? Does it need to also specify the type of gradient (.e.g linear, radial, concial, etc.)?
  </div></div>

  </section><section id="typography"><div class="header-wrapper"><h3 id="x9-7-typography"><bdi class="secno">9.7 </bdi>Typography</h3><a class="self-link" href="#typography" aria-label="Permalink for Section 9.7"></a></div>
  <p>Represents a typographic style. The <code>$type</code> property <em class="rfc2119">MUST</em> be set to the string <code>typography</code>. The value <em class="rfc2119">MUST</em> be an object with the following properties:</p>
  <ul>
  <li><code>fontFamily</code>: The typography's font. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#font-family">font family value</a> or a reference to a font family token.</li>
  <li><code>fontSize</code>: The size of the typography. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#dimension">dimension value</a> or a reference to a dimension token.</li>
  <li><code>fontWeight</code>: The weight of the typography. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#font-weight">font weight</a> or a reference to a font weight token.</li>
  <li><code>letterSpacing</code>: The horizontal spacing between characters. The value of this property <em class="rfc2119">MUST</em> be a valid <a href="#dimension">dimension value</a> or a reference to a dimension token.</li>
  <li><code>lineHeight</code>: The vertical spacing between lines of typography. The value of this property <em class="rfc2119">MUST</em> be a valid JSON string or a reference to a string token.</li>
  </ul>
  <aside class="example" id="example-typography-composite-token-examples"><div class="marker">
      <a class="self-link" href="#example-typography-composite-token-examples">Example<bdi> 35</bdi></a><span class="example-title">: Typography composite token examples</span>
    </div>

  <pre><code class="json hljs" aria-busy="false">{
    <span class="hljs-attr">"type styles"</span>: {
      <span class="hljs-attr">"heading-level-1"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"typography"</span>,
        <span class="hljs-attr">"$value"</span>: {
          <span class="hljs-attr">"fontFamily"</span>: <span class="hljs-string">"Roboto"</span>,
          <span class="hljs-attr">"fontSize"</span>: <span class="hljs-string">"42px"</span>,
          <span class="hljs-attr">"fontWeight"</span>: <span class="hljs-string">"700"</span>,
          <span class="hljs-attr">"letterSpacing"</span>: <span class="hljs-string">"0.1px"</span>,
          <span class="hljs-attr">"lineHeight"</span>: <span class="hljs-string">"1.2"</span>
        }
      },
      <span class="hljs-attr">"microcopy"</span>: {
        <span class="hljs-attr">"$type"</span>: <span class="hljs-string">"typography"</span>,
        <span class="hljs-attr">"$value"</span>: {
          <span class="hljs-attr">"fontFamily"</span>: <span class="hljs-string">"{font.serif}"</span>,
          <span class="hljs-attr">"fontSize"</span>: <span class="hljs-string">"{font.size.smallest}"</span>,
          <span class="hljs-attr">"fontWeight"</span>: <span class="hljs-string">"{font.weight.normal}"</span>,
          <span class="hljs-attr">"letterSpacing"</span>: <span class="hljs-string">"0px"</span>,
          <span class="hljs-attr">"lineHeight"</span>: <span class="hljs-string">"1"</span>
        }
      }
    }
  }
  </code></pre>
  </aside>

  <div class="issue" id="issue-container-number-102"><div role="heading" class="issue-title marker" id="h-issue-6" aria-level="4"><a href="https://github.com/design-tokens/community-group/issues/102"><span class="issue-number">Issue 102</span></a><span class="issue-label">: Typography type feedback <a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Feedback%2FReview%22" style="background-color: rgb(83, 25, 231); color: rgb(255, 255, 255);" aria-label="GitHub label: Needs Feedback/Review">Needs Feedback/Review</a><a class="respec-gh-label" href="https://github.com/design-tokens/community-group/issues/?q=is%3Aissue+is%3Aopen+label%3A%22dtcg-format%22" style="background-color: rgb(191, 212, 242); color: rgb(0, 0, 0);" aria-label="GitHub label: dtcg-format">dtcg-format</a></span></div><div class="">

  <p>Is the current specification for typography styles fit for purpose? <a href="https://github.com/design-tokens/community-group/pull/86#discussion_r768137006">Should the <code>lineHeight</code> sub-value use a number value, dimension or a new lineHeight type</a>?</p>
  </div></div></section></section>

      <section class="appendix" id="issue-summary"><div class="header-wrapper"><h2 id="a-issue-summary"><bdi class="secno">A. </bdi>Issue summary</h2><a class="self-link" href="#issue-summary" aria-label="Permalink for Appendix A."></a></div><ul><li><a href="#issue-container-number-72">Issue 72</a><span style="text-transform: none">: Group &amp; file level properties</span></li><li><a href="#issue-container-number-53">Issue 53</a><span style="text-transform: none">: Type: font family</span></li><li><a href="#issue-container-number-98">Issue 98</a><span style="text-transform: none">: Stroke style type feedback</span></li><li><a href="#issue-container-number-99">Issue 99</a><span style="text-transform: none">: Border type feedback</span></li><li><a href="#issue-container-number-103">Issue 103</a><span style="text-transform: none">: Transition type feedback</span></li><li><a href="#issue-container-number-100">Issue 100</a><span style="text-transform: none">: Shadow type feedback</span></li><li><a href="#issue-container-number-101">Issue 101</a><span style="text-transform: none">: Gradient type feedback</span></li><li><a href="#issue-container-number-102">Issue 102</a><span style="text-transform: none">: Typography type feedback</span></li></ul></section>


  <section id="references" class="appendix"><div class="header-wrapper"><h2 id="b-references"><bdi class="secno">B. </bdi>References</h2><a class="self-link" href="#references" aria-label="Permalink for Appendix B."></a></div><section id="normative-references"><div class="header-wrapper"><h3 id="b-1-normative-references"><bdi class="secno">B.1 </bdi>Normative references</h3><a class="self-link" href="#normative-references" aria-label="Permalink for Appendix B.1"></a></div>

      <dl class="bibliography"><dt id="bib-rfc2119">[RFC2119]</dt><dd>
        <a href="https://www.rfc-editor.org/rfc/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. S. Bradner.  IETF. March 1997. Best Current Practice. URL: <a href="https://www.rfc-editor.org/rfc/rfc2119">https://www.rfc-editor.org/rfc/rfc2119</a>
      </dd><dt id="bib-rfc8174">[RFC8174]</dt><dd>
        <a href="https://www.rfc-editor.org/rfc/rfc8174"><cite>Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words</cite></a>. B. Leiba.  IETF. May 2017. Best Current Practice. URL: <a href="https://www.rfc-editor.org/rfc/rfc8174">https://www.rfc-editor.org/rfc/rfc8174</a>
      </dd></dl>
    </section></section><p role="navigation" id="back-to-top">
      <a href="#title"><abbr title="Back to Top">↑</abbr></a>
    </p><div class="dfn-panel" hidden="" role="dialog" aria-modal="true" id="dfn-panel-for-dfn-design-tool" aria-label="Links in this document to definition: Design tool">
        <span class="caret"></span>
        <div>
          <a class="self-link" href="#dfn-design-tool" aria-label="Permalink for definition: Design tool. Activate to close this dialog.">Permalink</a>

        </div>
        <p><b>Referenced in:</b></p>
        <ul>
      <li>
      <a href="#ref-for-dfn-design-tool-1" title="§ 2. Introduction">§ 2. Introduction</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-2" title="§ 3. Terminology">§ 3. Terminology</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-3" title="§ 3.5 Type">§ 3.5 Type</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-4" title="§ 5.3 Description">§ 5.3 Description</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-5" title="§ 7. Aliases / references">§ 7. Aliases / references</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-6" title="§ 8. Types">§ 8. Types</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-7" title="§ 9.1 Groups versus composite tokens">§ 9.1 Groups versus composite tokens</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-8" title="§ 9.2.3 Fallbacks">§ 9.2.3 Fallbacks</a>
    </li><li>
      <a href="#ref-for-dfn-design-tool-9" title="§ 9.3 Border">§ 9.3 Border</a>
    </li>
    </ul>
      </div><div class="dfn-panel" hidden="" role="dialog" aria-modal="true" id="dfn-panel-for-dfn-translation-tool" aria-label="Links in this document to definition: Translation tool">
        <span class="caret"></span>
        <div>
          <a class="self-link" href="#dfn-translation-tool" aria-label="Permalink for definition: Translation tool. Activate to close this dialog.">Permalink</a>

        </div>
        <p><b>Referenced in:</b></p>
        <ul>
      <li>
      <a href="#ref-for-dfn-translation-tool-1" title="§ 2. Introduction">§ 2. Introduction</a> <a href="#ref-for-dfn-translation-tool-2" title="Reference 2">(2)</a>
    </li><li>
      <a href="#ref-for-dfn-translation-tool-3" title="§ 3.5 Type">§ 3.5 Type</a>
    </li><li>
      <a href="#ref-for-dfn-translation-tool-4" title="§ 6.2.3 Export tools">§ 6.2.3 Export tools</a>
    </li>
    </ul>
      </div><script id="respec-dfn-panel">(() => {
  // @ts-check
  if (document.respec) {
    document.respec.ready.then(setupPanel);
  } else {
    setupPanel();
  }

  function setupPanel() {
    const listener = panelListener();
    document.body.addEventListener("keydown", listener);
    document.body.addEventListener("click", listener);
  }

  function panelListener() {
    /** @type {HTMLElement} */
    let panel = null;
    return event => {
      const { target, type } = event;

      if (!(target instanceof HTMLElement)) return;

      // For keys, we only care about Enter key to activate the panel
      // otherwise it's activated via a click.
      if (type === "keydown" && event.key !== "Enter") return;

      const action = deriveAction(event);

      switch (action) {
        case "show": {
          hidePanel(panel);
          /** @type {HTMLElement} */
          const dfn = target.closest("dfn, .index-term");
          panel = document.getElementById(`dfn-panel-for-${dfn.id}`);
          const coords = deriveCoordinates(event);
          displayPanel(dfn, panel, coords);
          break;
        }
        case "dock": {
          panel.style.left = null;
          panel.style.top = null;
          panel.classList.add("docked");
          break;
        }
        case "hide": {
          hidePanel(panel);
          panel = null;
          break;
        }
      }
    };
  }

  /**
   * @param {MouseEvent|KeyboardEvent} event
   */
  function deriveCoordinates(event) {
    const target = /** @type HTMLElement */ (event.target);

    // We prevent synthetic AT clicks from putting
    // the dialog in a weird place. The AT events sometimes
    // lack coordinates, so they have clientX/Y = 0
    const rect = target.getBoundingClientRect();
    if (
      event instanceof MouseEvent &&
      event.clientX >= rect.left &&
      event.clientY >= rect.top
    ) {
      // The event probably happened inside the bounding rect...
      return { x: event.clientX, y: event.clientY };
    }

    // Offset to the middle of the element
    const x = rect.x + rect.width / 2;
    // Placed at the bottom of the element
    const y = rect.y + rect.height;
    return { x, y };
  }

  /**
   * @param {Event} event
   */
  function deriveAction(event) {
    const target = /** @type {HTMLElement} */ (event.target);
    const hitALink = !!target.closest("a");
    if (target.closest("dfn:not([data-cite]), .index-term")) {
      return hitALink ? "none" : "show";
    }
    if (target.closest(".dfn-panel")) {
      if (hitALink) {
        return target.classList.contains("self-link") ? "hide" : "dock";
      }
      const panel = target.closest(".dfn-panel");
      return panel.classList.contains("docked") ? "hide" : "none";
    }
    if (document.querySelector(".dfn-panel:not([hidden])")) {
      return "hide";
    }
    return "none";
  }

  /**
   * @param {HTMLElement} dfn
   * @param {HTMLElement} panel
   * @param {{ x: number, y: number }} clickPosition
   */
  function displayPanel(dfn, panel, { x, y }) {
    panel.hidden = false;
    // distance (px) between edge of panel and the pointing triangle (caret)
    const MARGIN = 20;

    const dfnRects = dfn.getClientRects();
    // Find the `top` offset when the `dfn` can be spread across multiple lines
    let closestTop = 0;
    let minDiff = Infinity;
    for (const rect of dfnRects) {
      const { top, bottom } = rect;
      const diffFromClickY = Math.abs((top + bottom) / 2 - y);
      if (diffFromClickY < minDiff) {
        minDiff = diffFromClickY;
        closestTop = top;
      }
    }

    const top = window.scrollY + closestTop + dfnRects[0].height;
    const left = x - MARGIN;
    panel.style.left = `${left}px`;
    panel.style.top = `${top}px`;

    // Find if the panel is flowing out of the window
    const panelRect = panel.getBoundingClientRect();
    const SCREEN_WIDTH = Math.min(window.innerWidth, window.screen.width);
    if (panelRect.right > SCREEN_WIDTH) {
      const newLeft = Math.max(MARGIN, x + MARGIN - panelRect.width);
      const newCaretOffset = left - newLeft;
      panel.style.left = `${newLeft}px`;
      /** @type {HTMLElement} */
      const caret = panel.querySelector(".caret");
      caret.style.left = `${newCaretOffset}px`;
    }

    // As it's a dialog, we trap focus.
    // TODO: when <dialog> becomes a implemented, we should really
    // use that.
    trapFocus(panel, dfn);
  }

  /**
   * @param {HTMLElement} panel
   * @param {HTMLElement} dfn
   * @returns
   */
  function trapFocus(panel, dfn) {
    /** @type NodeListOf<HTMLAnchorElement> elements */
    const anchors = panel.querySelectorAll("a[href]");
    // No need to trap focus
    if (!anchors.length) return;

    // Move focus to first anchor element
    const first = anchors.item(0);
    first.focus();

    const trapListener = createTrapListener(anchors, panel, dfn);
    panel.addEventListener("keydown", trapListener);

    // Hiding the panel releases the trap
    const mo = new MutationObserver(records => {
      const [record] = records;
      const target = /** @type HTMLElement */ (record.target);
      if (target.hidden) {
        panel.removeEventListener("keydown", trapListener);
        mo.disconnect();
      }
    });
    mo.observe(panel, { attributes: true, attributeFilter: ["hidden"] });
  }

  /**
   *
   * @param {NodeListOf<HTMLAnchorElement>} anchors
   * @param {HTMLElement} panel
   * @param {HTMLElement} dfn
   * @returns
   */
  function createTrapListener(anchors, panel, dfn) {
    const lastIndex = anchors.length - 1;
    let currentIndex = 0;
    return event => {
      switch (event.key) {
        // Hitting "Tab" traps us in a nice loop around elements.
        case "Tab": {
          event.preventDefault();
          currentIndex += event.shiftKey ? -1 : +1;
          if (currentIndex < 0) {
            currentIndex = lastIndex;
          } else if (currentIndex > lastIndex) {
            currentIndex = 0;
          }
          anchors.item(currentIndex).focus();
          break;
        }

        // Hitting "Enter" on an anchor releases the trap.
        case "Enter":
          hidePanel(panel);
          break;

        // Hitting "Escape" returns focus to dfn.
        case "Escape":
          hidePanel(panel);
          dfn.focus();
          return;
      }
    };
  }

  /** @param {HTMLElement} panel */
  function hidePanel(panel) {
    if (!panel) return;
    panel.hidden = true;
    panel.classList.remove("docked");
  }
  })()</script><script src="https://www.w3.org/scripts/TR/2021/fixup.js"></script></body></html>
